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The biggest name in little computers 1 



CUSTOM MANUFACTURED IN THE USA BY RADIO SHACK 
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A DIVISION OF TANDY CORPORATION 



This equipment generates and uses radio frequency energy. If not installed and used prop- 
erly, that is, in strict accordance with the manufacturer's instructions, it may cause interfer- 
ence to radio and television reception. 

It has been type tested and found to comply with the limits for a Class B computing 
device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference in a residential instal- 
lation. However, there is no guarantee that interference will not occur in a particular 
installation. 

If this equipment does cause interference to radio or television reception, which can be 
determined by turning the equipment off and on, the user is encouraged to try to correct the 
interference by one or more of the following measures: 

• Reorient the receiving antenna 

• Relocate the computer with respect to the receiver 

• Move the computer away from the receiver 

• Plug the computer into a different outlet so that computer and receiver are on different 
branch circuits. 

If necessary, you should consult the dealer or an experienced radio/television technician for 
additional suggestions. You may find the following booklet prepared by the Federal Com- 
munications Commission helpful: How to Identify and Resolve Radio-TV Interference 
Problems. 

This booklet is available from the US Government Printing Office, Washington, DC 
20402, Stock No. 004-000-00345-4. 



This equipment has been certified to comply with the limits for a Class B computing device, 
pursuant to Subpart J of Part 15 of FCC Rules. Only peripherals (computer input/output 
devices, terminals, printers, etc.) certified to comply with the Class B limits may be attached 
to this computer. Operation with non-certified peripherals is likely to result in interference to 
radio and TV reception. 



CHANGE OF ADDRESS 



NOTE: if you move, please fill out this card and return it so that you may continue to 
receive information regarding this program. « AfirrtlQl 
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OLD ADDRESS: 
Name - 



*JR on ? a /63 



Company . 

Address _ 
City 



State . 



Zip 



INSTRUCTIONS FOR USE 



1. Register one software package per card only. 

2. Complete the Software Registration portion of this form and mail it immediately. 
The Catalog No. may be found by examining the upper-right corner of your diskette. 



3. For convenience a change of address card has been included. Copy all information 

from the Registration Card onto it prior to sending the Registration Card. 



Model III Users 

XFERSYS UTILITY ON TRSDOS 1.3 

The Model III diskette in this package contains a NEW 
version of TRSDOS which is not compatible with OLD versions 
of TRSDOS. 

OLD TRSDOS diskettes to be used under the NEW TRSDOS MUST 
be XFERSYSed before use. Once XFERSYSed, an OLD TRSDOS 
diskette becomes a NEW TRSDOS diskette and should not be 
used with OLD TRSDOS again. If you started with an OLD 
system or data diskette, the XFERSYSed diskette will be a 
NEW system or data diskette respectively. 

OLD diskettes used under NEW TRSDOS without XFERSYSing, may 
cause extraneous information to be read at the end of 
files, giving a false End-of-File (EOF) indication. Some 
programs will not function properly under these conditions. 

NEW diskettes used under OLD TRSDOS, may not access all 
data and/or NEW programs may not run correctly. 

If you need to use the XFERSYS utility, see the TRSDOS 
section of your TRS-80 Model III Disk System Owner's 

Manual . 

Note: When changing from one TRSDOS to the other, you MUST 
press the RESET button each time the diskette in 
Drive is changed. You may also XFERSYS onto a NEW 
data disk. If this is done, all system files of the 
system diskette will be moved onto the data diskette. 

RADIO SHACK APPLICATION PROGRAMS WHICH WERE DELIVERED ON AN 
OLD TRSDOS DISKETTE SHOULD NOT BE XFERSYSed. 

OLD: TRSDOS 1.1 and 1.2. 

NEW; TRSDOS 1.3 

file: A collection of information stored as one 

named unit in the directory, 
program: A file which causes the computer to 

perform a function, 
data: Information contained in a file which is 

used by a program, 
system diskette: A diskette containing TRSDOS. When this 

diskette is placed in Drive and the 

RESET button is pressed, TRSDOS will begin 

to run. 
data diskette: A diskette which does not contain TRSDOS. 

If this diskette is placed in Drive and 

RESET is pressed, the screen will clear 

and "Not a SYSTEM Disk" will be displayed. 
XFERSYS: A program contained on the TRSDOS 1.3 

diskette. 
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Tips C n Load og Disk basic 

There are several ways, other than those described in the manual, to start up Disk basic. 

basic program -F.files -m: address 

program is a trsdos file specification for a Disk basic program. After start-up, Disk basic will run the 
program. This is optional. 

■F.files fells Disk basic the maximum number of files that may be open at one time, diesis a 
number from So 15. This is optional; if omitted, 3 is used. If Variable length files are 

needed, you must include the suffix v after files; otherwise, files will be Fixed length. 

-w.address tells Disk basic not to use memory above the specified address. This is optional; if 
omitted, Disk basic uses all memory up to Top. 

If all options are omitted, Disk basic will prompt with HOW MANY FILES? and memory? 

The options allow you to specify any or all of the following: 

• A program to run after Disk basic is started. 

• The maximum number of data files that may be Open at one time. The larger the number of files, 
the less area available for storing and executing your programs. (Note: Each Fixed length file takes 
up 360 bytes and each Variable length file takes up 616 bytes of memory.) 

• The highest address to be used by Disk basic during program execution. Omit this unless you are 
going to call machine-language subroutines. 



Under trsdos ready, if you type: 

BAS I C (ENTER) , Disk basic will enter the command mode once you answer the files and 
memory prompts. 

BASIC - F s 1 fEMTEff , Disk basic will Open one fixed length file and protect no memory. 

BASIC -M: 32000 (ENTER) , Disk basic will Open three fixed length files and will use 
memory no higher than 32000. 

BASIC PAYROLL - F : 3 ■>' (ENTER ). Disk basic will start-up. then load and run the basic 
program called payroll; three variable length files can be Opened, and basic can use all 
available memory. 

Note: If you PATCH Disk basic to prompt you for cassette speed when you enter Disk basic, you 
will still be prompted with CASS? no matter which option you use. 

Important Note for Model III trsdos 1.3 Users! 

The 1.3 version of trsdos will return with ERROR 31 (PROGRAM NOT FOUND) when you 
attempt to use the ROUTE command. 



Thank-You! 
I A Division of Tandy Corporation 
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TRS-80 Mode! Ill Disk System Owner's Man- 
ual: © 1980 Tandy Corporation, Fort Worth, 
Texas 76102 U.S.A. All Rights Reserved. 

Reproduction or use, without express written per- 
mission from Tandy Corporation or any portion of 
this manual is prohibited. While reasonable 
efforts have been taken in the preparation of this 
manual to assure its accuracy, Tandy Corporation 
assumes no liability resulting from any errors or 
omissions in this manual or from the use of the 
information obtained herein. 

Model III TRSDOS® Operating System: 
© 1980 Tandy Corporation, Fort Worth, Texas 
76102 U.S.A. All Rights Reserved. 



Model III BASIC Software: © 1980 Tandy Cor- 
poration and Microsoft. All Rights Reserved. 

The system software in the Model III microcom- 
puter is retained in a read-only memory (ROM) 
format. All portions of this system software, 
whether in the ROM format or other source code 
form format, and the ROM circuitry are copy- 
righted and are the proprietary and trade secret 
information of Tandy Corporation and Microsoft. 
Use, reproductions, or publication of any portion 
of this material without the prior written authori- 
zation by Tandy Corporation is strictly prohibited. 
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Congratulations on your purchase of the Model III Disk System. We think it's a 
valuable tool which will save you work as well as give you hours of enjoyment 
(or maybe both at once). You'll have all the power of the non-disk Model II!, 
plus the following features: 

• Your Computer can now be controlled by trsdos®, the powerful trs-so Disk 
Operating System, trsdos is included on a diskette with the Disk System. 

• Using trsdos, you can run a wide variety of programs, such as the Disk basic 
interpreter included on the trsdos diskette. 

• Each "system" diskette has approximately 126,720 bytes of storage available 
for your own programs and data; each "data" diskette has 178,944 bytes 
available. 

• You can load and save data at the approximate rate of 250,000 bits per second. 

• Your system can continue to grow in power and convenience. When Radio 
Shack issues improvements and enhancements to the system programs, you 
can "install" them simply by obtaining a new release of the trsdos diskette. 



Publications related to the use of the Model III Disk System: 

1. Model III Disk System Owner' s Manual (this manual). We'll call it the "Disk 
Manual" for short. 

2. Model III Disk System Quick Reference Card. 

3. Model 111 Operation and basic Language Reference Manual, the "Model III 
Manual" for short. 

4. Model HI basic Quick Reference Card. 

For Disk Operation: 

This Disk Manual supplements the Model III Manual. Use the Disk Manual as 
the primary source of information; we'll tell you when to refer to the non-disk 
Model III Manual. 

For Non-Disk Operation: 

To use the Computer as a non-disk system, all you need is the Model III 
Manual. 

For Programming Information: 

The Model III Manual contains most of the programming information, except 
that which pertains to disk input/output. In this manual, we will assume that you 
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are familiar with the basic programming definitions and details given in the 
Model III Manual. 



The Model III Disk System is intended for use by novices as well as 
experienced computer operators and programmers. In designing and writing this 
Disk Manual, we've tried to define and satisfy the needs of both groups: 

• Novices who might prefer a sequential presentation which emphasizes 
procedures and explains the purpose of various features. 

• Experienced users who might prefer a more analytical presentation which 
makes it easy to find specific information. 

In this manual, you'll find information that should satisfy your needs, whichever 
group you might belong to. 

The "Sample Sessions" are especially geared for novices, while the Technical 
Information chapters are for the more experienced users. 

Keep in mind, however, that it isn't necessary to read the entire manual to 
operate the Disk System. If you are only interested in Disk basic, for example, 
read the Operation section of this book and then turn directly to the Disk basic 
section. You can then go back to the trsdos section when you need to. 

Special Terms 

Even in the non-technical sections of this manual, we've had to use numerous 
special terms. Rather than scattering and repeating definitions throughout the 
book, we have used the following convention which we hope you'll find 
helpful. 

Special terms which are fully defined in another part of the manual are printed in 
boldface. Look up the word or phrase in the Index; this will tell you where the 
word is fully defined. 
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First set up the Computer according to the instructions in the Model III Manual. 

If you have a one- or two-drive system, installation is now complete. The built- 
in drives should be ready for use. 

If you have a three- or four-drive system, you need to connect the external 
drives. 



External Disk iirives 

The two external drives are not interchangeable. They have different Radio 
Shack Catalog Numbers and a few internal differences. 



First External Drive Purchased 
(Includes Cable) 

Second External Drive Purchased 



System 
Name 

'Drive 2/3' 



'Drive 2" 



Catalog 
Number 

26-1164 



26-1161 



The 26-1 164 drive may be used as Drive 2 or 3, depending on the number of 
drives in the system. In a three-drive system, it is always Drive 2 (the last 
drive). In a four-drive system, it is always Drive 3 (again, the last drive). 

The 26-1 161 drive may only be used in a four-drive system, in which it must be 
Drive 2. 

1 . Locate the flat "ribbon" cable that was included with the 26-1 164 drive. 
Notice that it has a single plug on one end, and two plugs clustered at the 
other end. See Figure 1 for plug labels. 

2. Connect the solitary "Computer" plug to the Disk Expansion Jack on the 
bottom rear of the Computer. See Figure 2. 

3. Now refer to Figure 3. Connect the external drive(s) to the other end of the 
cable, as follows: 

3-A. If you have one external drive (26-1 164): 

Connect it to the "Drive 2" plug near the middle of the ribbon cable. 

3-B. If you have two external drives (26-1 164 and 26-1 161): 

Connect the 26-1 164 to the "Drive 3" plug on the end of the cable. 
Connect the 26-1 161 to the "Drive 2" plug near the middle of the cable. 

4. Plug the external drive(s) into an appropriate source of AC power. Power 
requirements are specified on the unit and in the specifications given in this 
manual. 

You are now ready to start the Disk System. 
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Computer Plug 



Drive 3 Plug 




Figure 1. External Disk Cable with Plugs Labeled. 




Figure 2. Connection of the External Disk Cable to the Model 



2 



Attach the plug so the cable exits 
toward the rear of the Computer. 




EDGE CARD PLUGS GUIDE PIN 



GUIDE SLOT ■ 



Figure 3. Connection of external disk drives. 
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Operation 



First, take a few minutes to become familiar with the various elements of your 
Disk System. Refer to Figures 4 and 5. This is very important. If you try to use 
the Computer without having a little background information, you could damage 
a diskette. 




Figure 4. The Model III Disk System with External Drives (optional/extra). 



© Drive 0. The trsdos "system diskette" goes 
in this drive. 

© Drives 1, 2, and 3. These drives may 
contain "data diskettes." Data diskettes are 
described briefly in this chapter. 

© Drive Select led. When a drive is being 
accessed, its led lights up. 

© Drive Door. To insert or remove a diskette, 
open this door. Never remove a diskette 
while the led is lit, or while the diskette 
cohtains open files. 



© Reset Button. When you press this button, 
the Computer will attempt to load the 
operating system software from Drive 0. The 
trsdos diskette should be in Drive when 
you press this button. 

© Power Switch. All drives should be empty 
when you turn the Computer on or off. 
Otherwise, the information on the diskettes 
could be destroyed. 
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Figure 5. A Diskette. (Catalog Number 26-305, 26-405, or 26-406) 



© Storage Envelope. While a diskette is not in 
use, keep it here. 

© Write Protect Notch. When this is covered, 
the disk-drives cannot write (change infor- 
mation) on the diskette. Do not pinch the tab 
into the notch when you apply it. If the tab 
becomes indented, the disk drive may not 
sense that the disk is write-protected. Leave 
the notch uncovered if you want to save or 
change information on the diskette. 

© Jacket. The diskette is permanently sealed 
inside this protective jacket. Do not attempt 
to remove it. 



© Read/Write Window. The disk drive 
accesses the diskette surface through this 
window. Don't touch the diskette surface. 

© Label. To write on this label, use only a felt- 
tipped pen. Any other writing implement 
might damage the diskette. 



Diskettes 



In general, handle diskettes carefully, using the same precautions you use with 
tape cassettes and high-fidelity records. A small indentation, dust particle, or 
scratch can render all or part of a diskette unreadable — permanently. 

' Keep the diskette in its storage envelope whenever it is not in one of the 
drives. 

• Do not place a diskette in the drive while you are turning the system on or off. 

• Keep diskettes away from magnetic fields (transformers, ac motors, magnets, 
tvs, radios, etc.). Strong magnetic fields will erase data stored on a diskette. 
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• Handle diskettes by the jacket only. Do not touch any of the exposed surfaces. 
Don't try to wipe or clean the diskette surface; it scratches easily. 

• Keep diskettes out of direct sunlight and away from heat. 

• Avoid contamination of diskettes with cigarette ashes, dust or other particles. 

• Do not write directly on the diskette jacket with a hard point device such as a 
ball point pen or lead pencil; use a felt tip pen only. 

• Store diskettes in a vertical file folder on a shelf where they are protected from 
pressure to their sides (just as phono records are stored). 

• In very dusty environments, you may need to provide filtered air to the 
computer room. 

Tips on Labeling Diskettes 

Each diskette has a permanent label on its jacket. This label is for "vital 
statistics" that will never change. For example, to help keep track of diskettes, 
it's a good idea to assign a unique number to each diskette. Write such a number 
on the permanent label. You might also put your name on the diskette, and 
record the date when the diskette was first put into use. Remember, use only a 
felt tip pen for marking. 

This "permanent" label is not a good place to record the contents of the diskette 
since that will change, and you don't want to be erasing or scratching out 
information from this label. 



1. Turn all peripherals on. 

2. Turn the Computer on. Wait until all disk drive motors stop. 

3. Locate the trsdos diskette that was supplied with the Disk System. Insert it 
into Drive 0, with the label side facing up and the read/write window 
pointing into the drive slot. See Figure 6. 

4. When the diskette is fully inserted, close the drive door. 

5. Press reset. The Computer should now load trsdos and begin the start-up 
dialog described in the next section. 

If nothing happens on the Display, or if the message: DISKETTE? or NOT A 
SYSTEM DISK is displayed, check the following: 

• Are you using a trsdos "system" diskette? 

• Is the diskette properly inserted into Drive 0? 

• If external drives are present, are they properly connected and turned on? 
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Figure 6. Inserting a Diskette. 

If you can't find the problem, refer to the Troubleshooting and Maintenance 
chapter for further suggestions. 



TRSDOS Start-Up Dialog 

Whenever you reset the Model III Disk System, it loads trsdos and begins the 
start-up dialog. 

1 . The trsdos version number and date of creation will be displayed, followed 
by the amount of ram 02K or 4SK) and the number of drives in the system. 

2. trsdos will prompt you to enter the date in the form mm/dd/yy. For example, 
07/04/80 for July 4, 1980. Type in the correct date and press CENTER) , trsdos 
will not continue until you type in the date correctly. 

3. trsdos will prompt you to enter the time in 24-hour form hh:MM:SS. For 
example, 14:45:00 for 2:45 p.m. Type in the correct time and press (ENTER). If 
you don't wish to set the time, simply press CENTER) at the beginning of the 
line, trsdos will set the time to 00:00:00. 

4. trsdos will now display the message, TRSDOS READY 

Whenever this is displayed, you are in the trsdos ready mode, and you may 
type in a trsdos command. 
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Important Disk Operations 

In this section we will describe three very important operations: 

1 . Duplicating the trsdos diskette (backup) 

2. Initializing a data diskette (format) 

3. Converting files from Model I to Model III trsdos (convert). 

All new customers should complete the trsdos backup procedure now; multi- 
drive customers should also complete the format operation for a few diskettes. 
Detailed information is provided later in this manual; here we will simply 
outline the procedures. 

Making a BACKUP (Duplicate) of TRSDOS 



Your first operation should be to duplicate the trsdos diskette you received 
from Radio Shack. The trsdos diskette contains a utility program called 
backup to accomplish this. 

1 . Locate the trsdos diskette and a new, blank diskette. The trsdos diskette 
will be referred to as the "source," while the blank one will be called the 
"destination," during backup. 

2. Start trsdos as explained in the previous section. TRSDOS READY should be 
displayed. 

3. Type: BACKUP ( INTER) 

4. trsdos will now load and start backup. It will ask you: 

SOURCE DRIVE NUMBER? 

Specify the drive which contains the original trsdos diskette by typing: 



( ENTER) 

5. Next TRSDOS will ask: DESTINATION DRIVE NUMBER? 

Now specify the drive which will be used for making the duplicate trsdos. If 
you have two or more drives in your system, type: 1 (ENTER ) 

6. TRSDOS will ask: SOURCE DISK MASTER PASSWORD? 



Type: PASSWORD (ENTER) 

(password is the password of the supplied diskette.) 

Now' the duplication process will begin. 

If the destination diskette is not formatted, backup will format it before 

continuing. (Before any diskette can be used, it must be initialized or 

"formatted" — the data regions defined and labeled, and a table of contents 

or "directory" created.) 
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If you are using a single-drive system, trsdos will prompt you to swap 
source and destination diskettes several times during the formatting/backup 
process. 

After a single-drive backup, trsdos will display the message: 



INSERT SYSTEM DISKETTE CENTER) 

Be sure you have a trsdos diskette in Drive 0, then press ( ENTER) . 

The duplication process is now complete. We suggest you save the original 
trsdos and use the duplicate as your working copy. If anything happens to the 
working copy, you can make another one from the original. 



aking a Data Diskette (FORMAT) 

This section applies to multi-drive systems only. 

Drive must always contain a trsdos diskette, so the Computer can have 
access to the system programs stored there. Much of the storage capacity of this 
diskette is taken up by the system programs. 

However, the other drives in the system may contain "data" diskettes which 
have no system programs. All of the storage capacity of such diskettes is 
available for your programs and data. 

The format utility program takes a diskette and initializes or "formats" it. 
If the diskette was previously formatted, all prior information can be lost. 
The resultant diskette contains no system files and may only be used in 
Drive 1, 2 or 3. 

1 . In the trsdos ready mode, type: FORMAT (ENTER) 

2. trsdos will start the formatter program and ask you a series of questions: 
FORMAT WHICH DRIVE? 

Insert a blank diskette into Drive 1 . Type: 1 (EMTER) 

DISKETTE NAME? 

This name will serve as an internal label for the diskette. Type in any 
appropriate name of one to eight letters and numbers, starting with a letter. 
Press CENTER) at the end of the name. 

MASTER PASSWORD? 

The password may be from one to eight letters and numbers, starting with a 
letter. Press ( ENTER) at the end of the password. 

Use of the password allows backup, prot, and purge access to all non- 
system files. Unless special protection is needed, we suggest you use the 
password password. Whatever password you select, don't forget it! 
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If the diskette contains data, trsdos will warn you: 

DISKETTE CONTAINS DATA. USE DISK OR NOT? 

The warning is needed since format erases all previous infor mation from the 
diskette. Type N (ENTER) to cancel format; type Y (ENTER) or U (ENTER) to 
continue it. 

3. trsdos will now format and verify the diskette. The data diskette will then 
be ready for use in Drive 1, 2, or 3. 

Model I/III Conversion (CONVERT) 

In general, Model I trsdos diskettes cannot be used in a Model III Disk 
System. However, Model III trsdos includes a special program, convert, to 
read a Model I trsdos diskette and copy its non-system files onto a Model III 
trsdos diskette. 

In two-drive systems, the files must be copied onto a Model III system diskette; 
in three- or four-drive systems, the files may be copied onto a data diskette. 

Here are abbreviated instructions for using this program. For further details, see 

CONVERT. 

1 . Using a Model I Disk System, remove all passwords from the diskette to be 
converted. You can do this with the prot command, described in the Model I 
TRSDOS/Disk basic Owner's Manual. 

2. Start Model III trsdos. 

3. Place the Model I diskette in Drive 1 , 2 or 3. (In two-drive systems, use 
Drive 1; in three- or four-drive systems, Drive 2.) 

4. In three- or four-drive systems, place a Model III data diskette in Drive 1 . 



5. Type: CONVERT (ENTER) 

4. The conversion program will start by asking for the source drive number. 
Type in the number of the drive containing the Model I diskette, then press 
dNTM). 

5. Next, the conversion program will ask for the destination drive number. Type 
in the number of the drive containing the Model III diskette, then press 
(ENTER) . (In two-drive systems, use Drive 0; in three- or four-drive systems. 
Drivel.) 

6. Now all the non-system files will be converted and copied onto the 
destination diskette. As each file is copied, its name will be displayed. 

7. When the process is completed, you may remove the Model I diskette. It is 
unchanged by the convert program. The destination diskette contains the 
converted files. 

8. To restore password protection to the converted files, you may use the prot 
or attrib command. 
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Quick Instructions for Using Disk BASIC 

in this section we'll "walk you" through the following procedures: 

1 . Starting Disk basic 

2. Running a simple program 

3. Saving a program in a disk file 

4. Loading a program from a disk file 

For programming information, see the Disk basic section of this manual. 
Here we are showing procedures only. 



Starting Disk BASIC 



Under trsdos ready, type: BASIC (ENTER) 

The Computer will load and start basic. First, it will ask two questions. 
Press (ENTER) in response to each of them. 



HOW MANY FILES? ( INTER) 



MEMORY SIZE? (EMTER) 

A heading will be displayed, followed by: 

READY 

You may now begin using Disk basic. 



Saving a Program 

You should have a program in memory, and be in Basic's ready mode. Type: 



SAVE "PROGRAM" CENTER) 

basic should now save the program in a disk file we arbitrarily named 
"program." Any other suitable file name would do. 



Loading a Program 

For this sample session, we will load the program just saved. 



First type: NEW CENTER) to erase it from memory. (This is to prove that it can be 
retrieved from the disk file.) 
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Now type: LOAD "PROGRAM" (ENTER ) and basic will load the specified 
program. 

You may now list it and run it. 

For further information on using Disk basic, see Section 3 of this manual. 

Setting the Cassette Baud Rate under Disk 



trsdos sets the cassette baud rate to High. If you would like to change this, use 
the following trsdos command: 



PATCH BASIC/CMD ( ADD = 5202 >FIND = 00 >CHG = FF i (ENTER) 

Consequently, you will be prompted with: CASS? whenever you start Disk 
basic. 

You may then type either H (High) or L (Low) to choose the rate you need. 

To change the system diskette back to its original state (i.e., no CASS?), simply 
use the trsdos patch command again but reverse the find and chg values. 
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Troubleshooting and Maintenance 

If you have problems operating your Model III Disk System, please check the 
following symptoms and cures, and check the corresponding table in your 
Model III Manual. 

If you can't solve the problem, take the unit to your local Radio Shack. We'll 
have it fixed and returned to you as soon as possible. 



Symptom 


Cure 


Disk drive motors run 
continuously when the Computer 
is turned on. 


Check external drive connection sequence. 
Drive 26-1 1 64 must always be the last 
external drive. 


Computer will not load trsdos. 


1 . Make sure you have inserted the 
trsdos diskette properly in Drive 0. 

2. Make sure all peripherals are properly 
connected. 


Error Messages 


Look up the message in the trsdos or 
basic Error Message Section. The "cure" 
should be listed. 


Frequent disk i/o errors 


1 . Diskette is partially erased. Backup the 
diskette, then re-format it. 

2. Diskette is worn out. Use backup copy, if 
available, to make a new working copy. 

3. Disk drives need cleaning or alignment 
by Radio Shack service technicians. 



Maintenance 

For reliable operation, the disk drives must be kept clean and properly aligned. 
These procedures should be done by Radio Shack service technicians, according 
to the following schedule: 



Degree of Use 

Commercial data processing 
environment 

Occasional home use 



Maintenance Interval 
Every month for medium use. 

Every 8-10 months; more often if 
needed. 



For further instructions, see the Troubleshooting and Maintenance section in 
your Model III Manual. 
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For the sake of clarity and brevity, we've used some special notation and type 
styles in this book. 

capitals and punctuation 

indicate material which must be entered exactly as it appears. (The only 
punctuation symbols not entered are ellipses, explained below.) For example, 
in the line: 

DUMP LISTER (START = 7000, END = 7100JRA = 7004) 
every letter and character should be typed as indicated. 

lowercase italics 

represent words, letters, characters or values you supply from a set of acceptable 

values for a particular command. For example, the line: 

LIST filename 
indicates that you can supply any valid file specification after list. 

Ellipsis indicates that the preceding items can be repeated. For example: 

ATTRIB filename (option, . . .) 
indicates that several options may be repeated inside the parentheses. 



This special symbol is used occasionally to indicate a blank-space character 
(ASCII code 32 decimal, 20 hexadecimal). 

PRINT "HHHIH!" 

X '««««' 

Indicates that nnnn is a hexadecimal number. All other numbers in the text 

of this book are in decimal form, unless otherwise noted. 

X'7000' 
indicates the hexadecimal value 7000 (decimal 28672). 

COMPUTER TYPE 

Any words, letters, or numbers that are displayed on the screen will be in 
computer type (dot-matrix). Uppercase letters are used; however, your screen at 
times may display lowercase letters instead. 
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Specifications 



Diskettes 



Diskette Organization 
(Formatted Diskette) 



Operating Temperature 

Power Requirements 
(External Drives) 



5 l A" mini-diskettes 
Radio Shack Catalog 
Number 26-305, 
26-405 (package of three), 
or 26-406 (package of 10) 

Single-sided 

Double-density 

40 Tracks 

18 Sectors/Track 

256 Bytes/Sector 

55 to 80 Degrees Fahrenheit 
13 to 27 Degrees Celsius 

120 VAC, 60 Hz, 28 VA (240 VAC, 50 
Hz, Australian; 220 VAC, 50 Hz, 
European) 
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Description of TRSDOS 



What Is TRSDOS? 

trsdos (pronounced "triss-doss") stands for "trs-80 Disk Operating System." 
It fulfills three roles: 

1 . Master Program 

2. Command Interpreter 

3. Program Manager 

As the master program, trsdos enables the microprocessor and its various 
components to interact efficiently. The components include: 

• Random Access Memory (ram), trsdos reserves space for its own needs and 
allocates space for user programs. 

6 Disk Drives, trsdos interfaces with the disk hardware and provides a file 
system for storing system and user data on diskettes. 

e Input/output devices. These include the keyboard, video display, printer, and 
rs-232-c equipment. 

trsdos is also a command interpreter. Whenever it displays TRSDOS READY, 
you may enter commands that control how the system works. These are known 
as "library" commands. 

In its role as program manager, trsdos will load and run system or user 
programs. During this time, the system or user program is in control of the 
Computer. 

Figure 7 illustrates the relationships between these three roles. 



here Does BASIC Fit ta? 



Referring to Figure 7, you'll see that Disk basic falls under the "language 
package" category. 

Disk basic consists of some general enhancements to Model III basic, plus the 
disk input/output capability. It uses Model III basic (stored in rom) whenever 
possible. For instance, the Model III basic rom includes all of the mathematical 
functions. 

If you're used to the non-disk system, there's one difference you should 
understand from the beginning: In the non-disk system, basic is in control when 
you start-up. In the disk system, however, trsdos is in control when you start- 
up. You have to tell trsdos to load and run basic. Only then can you begin 
running a program written in basic. 
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trsdos is stored on the system diskette included with your Disk System. Each 
time the Computer is turned on or reset, the trsdos master program is loaded 
into ram so it can take charge. 

trsdos occupies approximately 40,000 bytes of space on the diskette; however, 
only a portion of that is in ram at once. This is possible because trsdos is 
divided into several independent "modules." 

The "resident" module is in memory at all times. It consists of input/output 
drivers, tables, the command interpreter, and other essential routines. 

Additional modules are loaded as needed, and replaced (or "overlaid") by other 
modules when they are no longer needed. 

Note: After you enter a library or utility command, you will usually hear 
trsdos accessing the system disk. It is loading an overlay module which 
contains the code necessary to complete the command. 

The Memory Map in Figure 8 illustrates how trsdos utilizes the available 
memory space. 
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Using TRSDOS 



Entering a Command 

Whenever the trsdos prompt. 

TRSDOS READY 

is displayed, you can type in a command, which can be no more than 63 
characters in length. You must press (ENTER) to end the line, trsdos will then 
"accept" the command. 

For example, type: CLS (ENTER) trsdos will clear the Display and the trsdos 
ready prompt will reappear. 

In general, your commands will require more than one word. For example, to 
kill (delete) a file named myname, you have to specify the command and the 
filename. 



KILL MYNAME (ENTER) 

tells trsdos to find the file named myname, eliminate it from the diskette, and 
release the space previously occupied by that file. 

Whenever you type in a line, trsdos follows this procedure: 

1. First it checks to see if what you've typed is the name of a trsdos command. 
If it is, trsdos executes it immediately. 

2. If what you typed is not a trsdos command, then trsdos will check to see if 
it's the name of a program file on one of the drives. 

3. When searching for a file, trsdos looks first through Drive 0, then Drive 1, 
etc., unless you include an particular drive specification with the file name 
— or specify the master command (see Library Commands). 

If trsdos finds a specified user file, it will load and execute the file if it is a 
program file. Otherwise, you'll get an error message. 



Command Syntax 

Command syntax is a command's general form (like the grammar or structure of 
an English sentence). The syntax tells how to use keywords (such as dir, list, 
create, etc.) together with the necessary parameters and punctuation. 

If you need help remembering the syntax form of a specific command while 
you're operating trsdos, type in: 



HELP command (ENTER) 
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command should be the specific Library Command you're having trouble with. 
TRSDOS will give you the syntax format as well as a brief definition of the 
command. 



Commands (Syntax Forms) 

No-file commands 



command (options) comment 

options is a list one or more parameters that may be needed by the 
command. Some commands have no options. The parentheses 
around options must he included unless the option itself is 
omitted. 

comment is an optional field used to document the purpose of the 
command. Comments are useful inside automatic command 
input fifes (see bu!ld and do). 



One-file commands 



m mat I Til m • 'op\ on l 'j < me if 

filesm n r s st nal; 7 o . ilk spec ica ii n 
Of, ions- See defin U 1 above 

comment— See definition above. 
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command filename delimiter filename (options) comment 
filename is a standard trsdos file specification. 
delimiter is a blank space. 
options — See definition above. 
comment — See definition above. 



File Specification 



The only way to store information on a diskette is to put it in a disk file. 
Afterwards, that information can be retrieved via the file name you gave the file 
when you created or renamed it. 

A file specification has the general form: 



filename/ext. pass word: d 

filename consists of a letter followed by up to seven optional letters 
or numbers. 

/extls an optional name-extension; 'ext' is a sequence of up to three 
letters or numbers, starting with a letter. 

.password is an optional password; 'password' is a sequence of up to 

eight letters or numbers, starting with a letter. 

;rfis an optional disk-drive specification; - d' is one of the digits 
0,1,2,3. 



Note: There can be no blank spaces inside a file specification, trsdos 
terminates the file specification at the first blank space. 

For example: FILEA/TXT. MANAGER:3 references the file named filea/txt 
with the password manager, on Drive 3. 
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The name, extension, and drive-specification all contribute to the uniqueness of 
a file specification. The password does not. It simply controls access to the file. 

File Names 

A file name consists of a name and an optional name extension. For the name, 
you can choose any letter, followed by up to seven additional numbers or letters. 
To use a name extension, start with a diagonal slash / and add no more than 
three numbers or letters; however, the first character must be a letter. 

For example: 

MODEL3/TXT INVENTORY DATA11/BAS 

NAMES/A 12 AUGUST/A 15 WAREHOUS 

TEST TEST1 TEST 1 /A 

are all valid and distinct file names. 

Although name extensions are optional, they are useful for identifying what type 
of data is in the file. For example, you might want to use the following set of 
extensions: 

/BAS for basic program 

/TXT for ascji text 

/CMD for machine-language command file 

/DAT for data 

One advantage of using extensions is that you can tell by just looking at the 
directory what kind of information a file contains. 

Another advantage is that trsdos can recognize certain extensions. For 
example, if a file has the extension /cmd, the trsdos will load and attempt to 
execute that file when you type: filename (ENTER) omitting the extension /cmd. 

Drive Specification 

If you give trsdos a command such as: KILL TEST/ A trsdos will search for 
the file test/a first in Drive 0, then in Drive 1 , 2, and finally in Drive 3 until it 
finds the file. 

Anytime you omit a drive-specification, trsdos will follow this sequence, 
unless you use the master command. 

It is possible to tell trsdos exactly which drive you want to use by specifying 
the drive. A drive specification consists of a colon followed by one of the digits 
0, 1 ,2, or 3, corresponding to one of the four drives you might be using. 

For example: KILL TEST/A: 3 tells trsdos delete the file test/a on Drive 3 
only. 
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Anytime trsdos has to open a file (e.g., to list it for you), it will follow the 
same sequence. When trsdos has to write a file, it will skip over any write- 
protected diskettes. 

Password 

You can protect a file from unauthorized access and use by assigning passwords 
to the file. That way, a person cannot gain access to a file without using the 
appropriate password. 

It's important to realize that every file has a password, even if you didn't specify 
it when the file was created. In such instances, the password becomes eight 
blank spaces. In this case, the file becomes unprotected — anyone can gain total 
access simply by referring to the filename. 

trsdos allows you to assign two passwords to a file: 
9 An "Update word," which grants total access to the information 
° An "Access word," which grants limited access to the information (see 
attrib) 

When you create a file, the Update and Access words are both set equal to the 
password you specify. You can change them later with the attrib command. 

A password consists of a period followed by one to eight letters or numbers. If 
you do not assign a password to a file, trsdos uses a default password of eight 
blanks. 

For example, suppose you have a file named secret/bas. and the file has 
myname as an update and access word. Then the command: KILL SECRETS/ 
BAS will not cause the file to be killed. You must include the password myname 
in the file specification. 

Suppose a file is named domain/bas and has blanks for the password. Then the 
command: KILL DOMAIN/BAS, GUESS will not be obeyed, since guess is not 
the password. 

A Few Important Definitions 

System vs. Data Diskettes 

A system diskette is one which contains the trsdos disk operating system 
software. Subject to space limitations, it may also contain your own files. A 
system diskette must always be in Drive while the Computer is in use. 

A data diskette, on the other hand, does not contain the operating system 
software, and therefore cannot be used in Drive 0. It may be used in Drive 1 , 2 
or 3. Such a diskette has a maximum of space available for storing your own 
programs and data. 
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System, Program, and Data Files 

System files include the trsdos operating system software, the basic language 
interpreter, the format, backup and convert utilities, and other software 
which is released by Radio Shack. These files appear in the Directory with an 
"S" attribute. (See dir) 

Program files are stored in a special format which allows them to be loaded and 
executed directly from the trsdos ready level. For example, the basic 
interpreter is a program file. 

Data files include all files that are not in the correct format to allow loading and 
executing from trsdos ready. For example, a program written in basic will be 
stored as a data file. It can be loaded and executed from basic, but not from 
trsdos ready. 

Master Passwords 

Each diskette is initially assigned a master password during format or backup. 
(Your master password for trsdos is password.) The master password allows 
you to use backup, purge, and prot on a diskette. Using a diskette's master 
password, you may change it (see prot). 
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TRSDOS library Commands 

APPEND 
Append iles 



append source-file destination-file 

source-file is the specification for the file which Is to be 
copied onto the end of the other file. 

destination-file is the specif tcatfQR far the file whic i is to 
receive the appendage (addition), 

Note: Both source- and destination-files mast M in sscn 
format (data files or Basse programs saved with the a 
option). 



append copies the contents of the source-file onto the end of the destination-file. 
The source-file is unaffected, while the destination-file is extended to include the 
source-file. 

Note: The logical record lengths must match. See dir for more information on 
logical record lengths. 

Examples 

APPEND WORDFILE/C WORDFILE/D 

A copy of wordfile/c is appended to wordfile/d. 

APPEND REGI0N1/DAT TOTAL/DAT, GUESS 

A copy of region 1/dat is appended to total/dat, which is protected with the 
password guess. 

Sample Uses 

Suppose you have two data files, payroll/a and payroll/b. 
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PAYROLL/A 



A t k i n s * W . R , , 
Baker * J.B. . . 
Chambers * C.P. 
D o d s o n f M * W . , 
Ki cKamon > T , Y. 



PAYROLL/E 



Lewis* G . E ♦ 
Miller* L . . 
Peterson* B , 
Rodriguez * F < 



You can combine the two files with the command: 

APPEND PAYROLL/B PAYROLL/A 
payroll/a will now look like this: 

PAYROLL/A 

Atkins * W.R, 
Baker* J.B. . . . . 
Chaiiibe rs > C.P. , 
D o d s o n > li ♦ W . ... 
Ki ck anion » T . Y . . 
Lewis* G . E . . ♦ , , 
Miller* L , , 
Peterson* B. ... 
Rodriguez* F . . . 

payroll/b will be unaffected. To see the APPENDed file, type LIST Pf 
(ASCII). 

Note: Do not load a program under basic after an append. 



JOLL/A 



Change a Fie 9 s Password 



attrib ills (visibilityMC = m ?£,upu= : ns.pwi = level) 

• ff/e is the file specification. 

visibility must be i or n. Tells trsdos whether the file is Invisible (i) or 
Non-invisible (n) (see dir). If omitted, visibility is unchanged. 

Acc=Mmete!is trsdos \k& access word. If minified the access word 

is utisiranyed. If acc = , is used, the access word is set to 

■ blanks. *■ - - 

upd = name tells trsdos the update word. If omitted, the update word 

is unchanged. If upd = , is used, tits update word is set to 
blanks. 



27 



i fiC '■':■■' 



*mmm 



prot = fei/e/ tells trsdos the protection level for access. If omitted, 
/eve/ is unchanged. 



Level 



Degree of acces s granted by access wo rd 



full Full access, no protection. 

kill Kill, rename, read, execute, and write (gives 

total access, i.e., the least-protected). 

name Rename, read, execute, and write. 

write Read, execute, and write. 

read Read and execute. 

exec Execute only. 

Note: Each level allows access to itself plus all lower levels. 



attrib lets you change the passwords to an existing file or makes the file 
invisible or non-invisible. Passwords are initially assigned when the file is 
created. At that time, the update and access words are set to the same value 
(either the password you specified or a blank password). 



ATTRIB DATAFILE ( I »ACC = JULY14 »UPD=M0USE * PR0T=READ ) 

Makes the file invisible, sets the access password to julyw and the update 
password to mouse. Use of the access word will allow only reading and 
executing the file. 

ATTRIB PAYROLL/BAS .SECRET (N»ACC=») 

Sets the access word to blanks. The file is made non-invisible and the protection 
level assigned to the update word is left unchanged. 

ATTRIB OLD/DAT, APPLES <UPD=») 
Sets the update word to blanks. 

ATTRIB PAYROLL/BAS, PW <PR0T=EXEC) 

Leaves the access and update words unchanged, but changes the level of access. 

Sample Uses 

Suppose you have a data file, payroll, and you want an employee to use the 
file in preparing paychecks. You want the employee to be able to read the file 
but not to change it. Then use a command like: 
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ATTRIB PAYROLL (I »ACC = PAYDAY ,UPD=AV0CAD0 *PR0T=READ ) 

Now tell the clerk to use the password payday (which allows read only;; while 
only you know the password, avocado, which grants total access to the file. 

Protecting BASIC Programs 

You may give a basic program execute-only protection using the attrib 
command. For example, suppose the program is named test (no password). 
Under trsdos ready, execute this command: 

ATTRIB TEST ( ACC= »UPD=VALLEY ,PR0T=EXEC ) 

Now test has a blank access password, an update password of valley, and an 
access level of execute only. Without using the update password, there is now 
only one way to execute the program: 

1. Start basic. 

2. Type: RUN "TEST" 

(This is the only way to access the program. If the operator attempts to load 
it instead, basic will erase the program from memory before returning with 

READY.) 

After the run "test" command, basic will load and execute the program. If 
the operator presses (BREAK) or if the program ends normally, basic will erase the 
program before returning with the ready message. This makes it impossible to 
obtain a listing of the program — unless the update password is used. 

Of course, if you use the update password, you may gain full access to the 
program. 



auto eemmatwl-liae 

command-line gives frsdos a command or the name of an mautable 

program file created fay build. 

if command'Hne is giwem, the command will fce executed on reset/ 
power-up. 

if commnK i -v<,8i& omitted the previous mjto command is unz^l 
Iran the diskette. 
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This command lets you provide a command to be executed whenever trsdos is 
started (power-up or reset). You can use it to get a desired program running 
without any operator action required, except for typing in the date and time. 

When you enter an auto command, trsdos writes command-line into its start- 
up procedure, trsdos does not check for valid commands; if the command line 
contains an error, it will be detected the next time the System is started up. 



AUTO DIR (SYS) 

Tells trsdos to execute the command dir (sys) after the start-up procedure. 
Each time the System is reset or powered up, it will automatically execute that 
command after you enter the date and time. 

AUTO BASIC 

Tells trsdos to load and execute basic each time the System is started up. 

AUTO FORMS (WIDTH=80) 

Tells trsdos to reset the printer width parameter each time the System is started 
up. 

AUTO PAYROLL/CMD 

Tells trsdos to load and execute payroll/cmd (must be a machine-language 
program) after each System start-up. 

AUTO DO STARTER 

Tells trsdos to take automatic key-ins from the file named starter after each 
System start-up. See build and do. 

To Erase an AUTO Command 



Type: AUTO ( INTER) 

This tells trsdos to erase any automatic command. The command will be 
deleted the next time you power-up or reset the System. 

The acknowledgement: AUTO = "" is displayed after an erasure. 

To Override an AUTO Command 

You can bypass any automatic command by holding down (ENTER) while pressing 
reset. You must continue holding down ( ENTER) until you are prompted for the 
date during the initialization process. 
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BUILD 

Create an Automatic Commai 



file is a -file specification which cannot include an extension. 



This command lets you create an automatic command input file which can be 
executed via the do command. The file must contain data that would normally 
be typed in from the keyboard to the trsdos ready mode. 

build files are intended for passing command lines to trsdos just as if they'd 
been typed in at the trsdos ready level. Note: clear cannot be used in a do 
file. 

When you enter the build command, build creates the file and immediately 
prompts you to begin inserting lines. Each time you complete a line, press 
(JEN TIB). (While typing in a line, you can use the usual cursor control keys for 
erasures and corrections.) 

To end the build file, simply press (BREAK) at the beginning of a line. 

First type: BUILD filename 

You will then be prompted to type in the command text. You then type in up to 
63 characters, then press ( ENTER) . You may enter as many lines as necessary. 
Press (BREAK) to quit and return to trsdos ready. 

A Sample BUILD-Fiie 

Here's a hypothetical BUiLD-file that initializes the serial interface and the printer 
driver: 



BETCOM <BAUD=1200,WAIT) 

FORMS (WIDTH=B0) 

PAUSE SERIAL INTERFACE & 



'INTER INITIALIZED 
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Clear User Memory 



CLEAR (STAR! = 33a>3,ESW - • &#M»,MEM = fffffffi) 

start = aaa3 tells TRSDOS where to start clearing user memory, aaaa 
is a four-digit hexadecimal number from 6Qoo to the end of user 
memory. If this option is omitted. 6000 is used. If this option is 

end = bbbb teils trsoos to clear user memory to a specified end. bbbb 
is a four-digit hexadecimal number no less than the start 
numbei and rse assist than iho 101,1 ol memory. If this option is 
used, start = aaaa must also be used. 

mem = «« se»& sfi-e memory protect address ccce is a ' >ur-digit 
hexadecimal number from nuuu to vrr?. If this option is omitted, 
the memory protect address is reset to end of user ram. 

i ill options are omitted all a faiiable ram ir ;leai bo\ me r.j;*'- 
protect is reset to end of memory, the Display is cleared, all i o 

drivers are reset (see Memory Requirements of rRSoos). 



This command gets you off to a fresh start. 

Depending on the options you select, this command will: 

9 Zero user memory (load binary zero into each memory address above 6000) 

• Clear the Display 

• Un-protect all memory 

See Memory Requirements of trsdos for more information on the memory- 
protect address. Note: clear cannot be used in a do file. 

Example 

CLEAR (START=9000tEND=0A000) 

Note: Hexadecimal numbers which begin with a letter must be prefaced by zero 
(see above example). 

CLEAR (MEM=7000) 
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CLOCK 

Turn Oo Clock Display 



clock {switch) 

svi/iich gives trsdos one of two options, on or off. 
If option is omitted, trsdos uses on. 



This command controls the real-time clock display in the upper right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Clock display is off at trsdos start-up. 

Note: Except during cassette and disk i/o, the real-time clock is always running, 
regardless of whether the clock display is on. 

Examples 

CLOCK 

Turns on the clock display. 

CLOCK (OFF) 

Turns the clock display off. 

See time and date. 



CLS 

Clear the Screen 



CLS 



This command clears the Display and puts it in the 64 character/line mode. 

Example 

CLS 
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Copy a File or Files 



Three forms: 

A) copy source-file destination-file 

source-file is a file specification for the file to be copied. 

destination-file is a file specification for the name and drive of the 

duplicate file. 

B) copy source-file :d ' 

source-file is defined above. 

:d tells trsdos to copy the file onto drive d, using the same file name. 

C) copy I exf.d 

eat is a 'wild-card'* file specificz-tiOR in which the fife name is 
omitted and the extension is given, trsdos will copy all files 
which have a matching extension, regardless of the file name. 

. - -J Is defined above. 



This command copies source-file into the new file defined by destination-file. 
This allows you to copy a file from one disk to another, using a single drive if 
necessary. (In the latter case, you must include drive specifications in both file 
specifications.) For single-drive systems (Drive 0), both diskettes must contain 
trsdos. (i.e., Data diskettes aren't allowed in Drive 0.) 

Examples 

COPY OLDFILE/BAS NEWFILE/BAS 

Copies oldfile/bas into a new file named newfile/bas. trsdos will search 
through all drives for oldfile/bas, and will copy it onto the first disk which is 
not write-protected. 

COPY NAMEFILE/TXT si 

This command specifies a file named namefile/txt to another disk. 

COPY FILE/EXTS0 si 

This command copies file/ext from Drive to Drive 1 . 
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COPY /BAS:0 :1 

tells trsdos to copy all Drive files which have the extension /bas. The files 
will be copied onto Drive 1 , using their present file names and extensions. 

Sample Use 

Whenever a file is updated, use copy to make a backup file on another disk. You 
can also use copy to restructure a file for faster access. Be sure the destination 
disk is already less segmented than the source disk; otherwise the new file could 
be more segmented than the old one. (See free for information on file 
segmentation.) 

To rename a file on the same disk, use rename, not copy. 



create fibnsme {lrl = saa.Rtc = & 

filename is She file specification. 

lhl = ma is the logical record length, aaa is a decimal number 
between zero and 255. if omitted. 256 is assumed. 

rec = 6M is the number of records to allow 'or. bbh is the sBirmv n 

records des red l* omitted, no resriMJi are allocated 



This command lets you create a file and pre-allocate (set aside) space for its 
future contents. This is different from the default (normal) trsdos procedure in 
which space is allocated to a file dynamically, i.e., as necessary when data is 
written into the file. 

If you open the file for sequential writes, trsdos will de-allocate (recover) any 
unused granules when the file is closed. If you open the file for random access, 
trsdos will not de-allocate space when the file is closed. 
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You may want to use create to prepare a file which will contain a known 
amount of data. This will usually speed up file write operations. File reading 
will also be faster, since pre-allocated files are less segmented or dispersed on 
the disk — requiring less motion of the read/write mechanism to locate the 
records . 

Examples 

CREATE DATAFILE/BAS (REC=300> LRL=0) 

Creates a file named datafile/bas, and allocates space for 300 256-byte 
records . 

CREATE NAMES/TXT. IRIS ( LRL = G4 »REC = 50 ) 

Creates a file named names/txt protected by the password iris. The file will be 
large enough to contain 50 records, each 64 bytes long. 

CREATE PAYROLL/BAS 

Creates a file named payroll/bas but allocates no space to it. 

Sample Use 

Suppose you are going to store personnel information on no more than 250 
employees, and each data record will look like this: 

Name (Up to 25 letters) 

Social Security Number ( 1 1 characters) 

Job Description (Up to 92 characters) 

Then your records would need to be 25 + 1 1 + 92= 128 bytes long. 

You could create an appropriate file with this command: 

CREATE PERSONNL/TXT ( REC=250 >LRL= 12B ) 

Once created, this pre-allocated file would allow faster writing than would a 
dynamically allocated file, since trsdos would not have to stop writing 
periodically to allocate more space (unless you exceed the pre-allocated 
amount). 

DATE 

Reset or Get Today's Date 



bate mm/dd/yy 

mm dd yy is the specification for the month {mm), day {dd) and 
year {yy). 
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Each must be a two-digit decimal number between the following 

ranges: 

mm 01-12 
dd 00-31 
yy 00-99 

The specifications are an option; however, if one specification is 
used, they all must be used. 

If mrn/dd/yy is omitted, trsdos displays the current date. 

II mm/dd yy & glvei , iksdos resets the Dale 



This command lets you reset the date or display the date. 

You initially set the date when trsdos is started up. After that, trsdos updates 
the date automatically, using its built-in calendar. You can enter any two-digit 
year after 1900. 

When you request the date, trsdos displays it in the format: 07/Z5/80 for July 
25, 1980. 

Examples 

DATE 

Displays the current date. 

DATE 07/18/80 

Resets the date to July 18, 1980. 




DEBUG 

Start Debug Monitor 



DEBUG 



This command starts the debug monitor, which allows you to enter, test, and 
debug machine-language programs. 
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Its features include: 

• Full- or half-screen displays of memory contents 

' Commands for modifications to ram and register contents 

• Single-step execution of programs 

a Breakpoint interruption of program execution 

• Transfer of control (Jump) 

• "Editing" of disk-files 

debug uses the memory area from X'4E00' to X'54FF* (see trsdos Memory 
Map), debug can only be used on programs in the user area X'550cr to top. 

Examples 

DEBUG 

Turns debug on. Press ® to quit debugging and return to trsdos. 



Q 



Turns debug off. 



Command Description 

Debug commands are usually entered by pressing a single key. In most cases, 
you do not have to press (ENTER) after the command has been typed in. Either 
a prompt will immediately be displayed or debug will execute the operation 
without further instruction. 

In some cases, you will have to enter a specific hexadecimal value or address 
(see r and J commands, for instance). Instead of pressing (ENTER) after the 
address is typed in, you will have to press CS PACEBA R). 

Once you have entered the debug program, you may use any of the following 
special commands: 

D (Display Memory Contents) 

Press © to display the contents of memory, trsdos will respond with the 
prompt: D ADDRESS = You should type in the hexadecimal address of the 
memory location you wish to see. 

The display will be either half- or full-screen, depending on the format you are 
currently using (see below). 
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X (Half-Screen Display) 

Press ® to put the Display in the half-screen format. A 128-byte block of 
memory will be displayed starting with the next lowest address which is a factor 
of 16. 

Figure 9 shows a typical half-screen format. 

S (Full-Screen Display) 

Press © to display the contents of a 256-byte block of memory starting with the 
next lowest address which is a factor of 256. 

Note: The last 16 bytes on the Display will be overlaid by any command line 
typed in after the full-screen display is updated. 

M (Modify RAM) 

Press (HD to change to the disk utility display format (see the f command). 
trsdos will respond with the prompt: M ADDRESS = You should type in the 
four-digit hexadecimal address of the memory location you wish to modify, 
followed by a blank space (anything other than a space will abort the 
command). 

The display will change to the memory edit format. The cursor will appear as a 
blinking character at the specified location. 

To exit the modify mode, press ( ENTER) to keep all changes made. 

R (Change Register Contents) 

Type: 



n as, 6M>ft (spacebar: * 

aa is 1Mb name of one of the register pairs af, bc, de, hc, or pc. 

bbbb is the four-digit hexadecimal value which will be loaded into aa. 

U fewer than four digits are typed In before pressing (spacebar) . 
leading zeros are sssumect. 



I (Instruction Single-Step) 

Pressing CD will allow the Computer to execute a single z-80 instruction. The 
display will then be updated. 



TRSDOS I 
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Start address 
of one 16-byte 
"row" of RAM 







m 



RAM display- 
hex contents 
of each byte 



mm 



ASCII display 

(• indicates a 

nondisplayable 

character) 



Z-80 register contents ' 
Op-code Instructions at the "PC" address 



Figure 9. Half-Screen Format. 



The instruction in the memory contents referenced by the program counter is 
executed. The program counter is increased by the appropriate value, and the 
control is returned to debug. 

debug will not, however, step through a call or jump into a rom address. 



C (Call Single-Step) 

If you wish to complete an entire call/return sequence, press ©. The call is 
then executed and control is returned to debug when the subroutine returns. 
Otherwise, this instruction acts just like the I command. 

You will not be able to step through a call or jump into a rom address. 



U (Update) 

Pressing (U) causes the Display to be updated repeatedly. Press any key to exit 
from this mode. 
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; (Increment Display Address) 

If the Display is half-screen, the first location shown is incremented by 16 when 
you press CD- If the full-screen format is displayed, the starting address will be 
incremented by 256. 

— (Decrement Display Address) 

If the Display is half-screen, the first location is decremented by 16 when you 
press Q. If the full-screen format is displayed, the starting address will be 
decremented by 256. 

J (Jump) 

Press GD to transfer control to a machine-language program, setting optional 
breakpoints. 

Debug will respond with the prompt: J ADDRESS? = 

You may type in a jump address and a breakpoint address. The command is 
terminated when you press (ENTER) . Type in the addresses in one of three 
formats: 



T RSDOS 



mm 



j address? = aaaa, bbbb Center) 

j address? = aaaa CI11I1) 
jaddbess? = .bhbb m tm 

aaaa is a four-digit hexadecimal address specifying the jump 

destination- if omitted, the address in the pc register is used. 

bbbb is a four-digit hexadecimal address specifying a breakpoint. 

Before the Computer executes an instruction at this address, it 
will retura control to debug. If this address h omitted, control 
will no! return to debug. 



Notes: Breakpoints must be set at the beginning of z-80 instructions. You may 
not set breakpoints in ROM addresses. The breakpointed address will contain an 
XT7' until the breakpoint is encountered. Then the original contents will be 
restored and debug will take control again. 

Q (Quit) 

Pressing (D turns off debug and returns control to trsdos. 
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F (File Patch Utility) 

This command lets you load and modify the contents of a diskette file. 

When you press 2D, debug will respond with the prompt: FILESPEC?. Enter the 
name of the file to be patched. 

debug will set up a full-screen display showing the first 256 bytes in the file. 
You can "page" through the file using the CD and ED keys. 

Figure 10 gives a typical display. 

In this file-display mode, both hexadecimal and ascii are given for each byte. If 
a code has no displayable character, a period is shown in the ascii area. 

The display control commands are like those for the normal file-display mode: 

CD Next page 
CD Previous page 

To change the file contents, press (M). This puts you in a modify-memory mode 
like the one previously described. Use the arrow keys to position the cursor (a 
blinking character), then type in the correct contents as a hexadecimal value. 
When you are through changing a page on the display, press (ENTER) . The 
diskette file will be updated and you will be returned to the file-display mode. 

To cancel changes made, do not press [ENTER) , press [B REAK) . This will put you 
back in the file-display mode without updating the diskette file. You may press 
CD then CD to restore the page display to its actual contents. 

To quit patching a file, press (BREAK) while in the file display mode, debug will 
prompt you for a new file specification. Press (BREAK) again and you will be 
returned to trsdos ready. 
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Drive # Record # 



Byte Offset 
within Record 



Hexadecimal Contents of 
Each Byte , 



ASCII Translation 



f/m 
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Figure 10. Full-Screen Format 
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List the Diskette Directory 



DIR :d(lNV,SYS,PRT) 

:dl$ the desired drive directory. If omitted, Drive is assumed. 

inv lists the invisible user files, if omitted, non-invisible user files are 
listed. 

sys lists system and user files, if omitted, only non-invisible user files are 

listed. 

prt lists the directory to the Printer. 1" omitted, in* directory will be listed 
on the Video Display only. 

If no option is given, trsdos lists non invisible user files in Drive 0. 



This command gives you information about a disk and the files it contains. 

To pause the listing, press (W). To continue, press ( ENTER) . To terminate the 
listing, press ( BREAK) . 

Examples 

DIR 

Displays the directory of non-invisible user files in Drive 0. 

DIR :1 (PRT) 

Lists the directory of the user files in Drive 1 to the Printer. 



Sample Directory Listing 

(See Figure 11.) 

Definition of column headings 



© File Name — The name and extension assigned to a file when it was created. 
The password (if any) is not shown. 

© Attributes — A four-character field. 

The first character is either i (Invisible) or n (Non-invisible). 

The second character is s (System) or * (User) file. 

The third character gives the password protection status: 
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/ / 



/ ./ / 
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Figure 11. Directory Listing. 

x The file is unprotected (no password). 

a The file has an access word but no update word, 

u The file has an update word but no access word. 

B The file has both update and access words. 

The fourth character specifies the level of access assigned to the access word: 

Total access 

1 Kill file and everything listed below. 

2 Rename file and everything listed below. 

3 This designation is not used. 

4 Write and everything listed below. 

5 Read and everything listed below. 

6 Execute only. 

7 No access. 

® Number of Free Granules — How many free granules remain on the diskette. 

© Logical Record Length — Assigned when the file was created. 

© Number of Records — How many logical records have been written. 

© Number of Granules — How many granules have been used in that 
particular file. 



Mmmem MMWMfflBBmm 
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© Number of Extents — How many segments (contiguous blocks of up to 32 
granules) of disk space are allocated to the file. 

© End of File (eof) — Shows the last byte number of the file. 

® Creation Date — When the file was created. 



Begin Aeto Command Input from a BUILD-FIle 



do command-line 

command-line is the name of file created with build. No extension should 
be specified. ii";£ file will automatically be given tine extension Bin, 



This command reads and executes the lines stored in a special-format file 
created with the build command. The System executes the commands just as if 
they had been typed in from the Keyboard. 

Command lines in a build file may include library commands or file 
specifications for user programs. 

When do reaches the end of the automatic command input file, it returns control 

to TRSDOS. 

The debug and clear command cannot be included in a build file. 

In addition to executing trsdos library commands, you can load and execute 
user programs from a DO-file. You will probably want to make your program 
name be the last line in the DO-file. 

Examples 

DO STARTER 

trsdos will begin automatic command input from starter, after the operator 
answers the Date and Time prompts. 

AUTO DO STARTER 

Whenever you start trsdos, it will begin automatic command input 
from starter. 
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Sample Uses 

Suppose you want to set up the following trsdos functions automatically 
on start-up: 

FORMS (WIDTH =80) 
CLOCK (ON) 

Then use build to create such a file. If you called it begin, then use the 
command: AUTO DO BEGIN to perform the commands each time TRSDOS 
starts up. 



Duplicate Output to Video and Printer 



dual {switch) 

switch is one of two options, on or off. II omitted, trsdos uses on. 



This command duplicates all video output to the Printer, and vice versa. It takes 
effect immediately. 

Notes: 

1 . Video and printer output may be different because of intrinsic differences 
between output devices and output software. 

2. Using the dual command will slow down the video output process. 

3. The dual command cannot be used during route and vice versa. 

4. The printer should be ready when you execute the command. 

Sample Use 



For a printed copy of all system/operator dialog, type: DUAL (EMTER ) 



To turn off the dual process, type: DUAL ( OFF ) ( ENTER ) 
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DUMP 

Store a Program Into a Disk File 



dump file (start = aaaa, end = bbbbjm = ccccrelo = tfcteW) 

fffe is the file specification 

start = sasa is the start address cf memory black, aaaa must be a four- 
digit hexadecimal number greater than or equal to x'7000.' 

end = bbbb is the end address of the memory block, bbbb must be a four- 
digit hexadecimal number. 

tra = cccc is the transfer address where execution starts when the program 
is loaded, cccc must be a four-digit hexadecimal number. If this 
option is omitted, the command will default to trsdos re-entry. 

relo = dddd is the start address for relocating or loading the program back 
into memory. cfcWtf must be a four-digit hexadecimal number. If this 
option is omitted, no relocation will take place. 

Mote: Addresses must be hexadecimal form, without the x' ' notation. 

You must add the prefix "0" to any hex number which begins with a 
letter. 



This command copies a machine-language program from memory into a 
program file. You can then load and execute the program at any time by entering 
the file name in the trsdos ready mode. 

Examples 

DUMP LISTER ( START = 7000 >END=7100 ,TRA=7004 ) 

Creates a program file named lister/cmd containing the program in memory 
locations x - 7000" to x'7ioo\ When loaded, lister/cmd will occupy the same 
addresses, and trsdos will protect memory beginning at x'70oo\ The program is 
executable for the trsdos ready mode. 

DUMP PR0G2 (START=7000»END=7F00»TRA=8010(RELO=8000> 

Creates a program file named prog2/cmd containing the program in addresses 
x - 7000- to x'7foo'. When loaded, prog2/cmd will reside from x'sooo' to x'SFucr. 
Execution will start at x'soio*. 
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ERROR 

Display Error Message 



error number 

number is a decimal number for a trsdos error code. 



This command displays a descriptive error message. For example, after 
receiving the message, * * ERROR 47 * * you may respond with the 
command: ERROR 47 (ENTER ) and trsdos will display the full error message. 

For a complete list of error codes and messages, see the Technical Information 
section of this manual. 



FORMS 

Set Printer Parameters 



FORMS (WIDTH = W, LINES = I) 

width = wis the maximum number of characters per output line. If a line 
reaches this length, trsdos will insert a carriage return to force a new 
Sine. If this option is omitted, the current maximum width will be 
used. To disable the maximum line width feature, use width = 255. 
trsdos will not force new lines. 

lines = / is the number of Sines per page, trsdos does not use this value. 
However, basic will use it in computing the necessary page 
displacement for execution or if lprint ckrs(12j is executed. If lines = / 
is omitted, the current value is used. 



This command lets you modify the printer forms control features of trsdos. 
The default values are: 

Maximum line width: 132 
Lines/page: 60 
forms also sets the line count to 0. 



49 



. JtJ.3 TF1S-80 MODEL 111 DISK SYSTEM 



Examples 

If you are using 8'/2"-wide forms, you will probably want to set width = 80: 

FORMS (WIDTH=80) 

If you are using 14"-long forms, you may want to set lines = 78. 

FORMS (LINES=7B) 

This change will allow the basic statement, lprintchr$02), to advance a page 
by the correct number of lines. 

Notes: 

1. The width you specify is stored in ram location 16427. The lines you 
specify is stored in ram location 16424. 

2. The Printer must be ready when you execute this command. 



FREE 

Display Disk Allocation Map 



mum 



FREE :tf(PRT) 

:tf is the drive specification. 1! omitted, Drive is used. 

(prt) tells trsoos to send the map to the Printer. 

it emitted, trsdos sends the map to the Video Display only. 



This command gives you a map of granule allocation on a diskette. (A granule, 
1280 bytes, is the unit of space allocation.) It also shows the location of the 
directory and any flawed sectors. 

When a diskette has been used extensively (file updates, files killed, extended, 
etc.), files often become segmented (dispersed or fragmented). This slows the 
access time, since the disk read/write mechanism must move back and forth 
across the diskette to read and write to a file. 

free helps you determine just how segmented your disk files are. If you decide 
you'd like to re-organize a particular file to allow faster access, you can then 
copy it onto a relatively "clean" diskette. 
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Examples 

FREE 

Displays a free space map of the diskette in Drive 0. 

FREE (PRT) 

Lists the free space for Drive to the Printer. 

FREE si (PRT) 

Lists the Drive 1 map to the Printer. 

A Typical FREE Display 

Four special symbols are used in the free map. 
Unused Granule 
Direct Directory Information 
X Allocated Granule 

Flawed Granule Contains a Flawed Sector (Unusable) 

A typical free map display is shown in Figure 12. 



Disk Name 
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All six granules in 
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Figure 12. Free Map. 
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1 The directory is located 
on track 17. 



HFT P 

Explanation of TRSDOS Command 



help command 



command is the specific trsdos command or subject on which wou need 
help. If omitted or if an invalid subject is given, trsdos will list all 
available subjects. 



i 



51 



I i;v^ t 



\wP!fflPi$if 



;qn] 



YSTEM 



' WBBM SB/SBBBS&MBHttM BSBMM 



If you type in the following: HEELP BACKUP (ENTER) trsdos will respond with 
the syntax format, a definition of the command, and an explanation of 
the abbreviation. 

HELP SYNTAX tells trsdos to explain the help descriptions. 



KILL 

Delete a File or Group of Files 



Two syntaxes: 



A) kill file 

file is a file specification 

B) kill iextd 

/ex/ is a file extension that must contain three characters. 

:d is a drive specification. It musihs provided. 



This command deletes one file or a group of files, depending on which form is 
used. Form A deletes the specified file. If no drive specification is given, 
trsdos deletes the file from the first diskette that contains it. 

Form B deletes all files with a specified extension, regardless of the file name of 
each file. If no drive specification is given, the files will be deleted from the first 
drive that contains a matching file specification. 

Examples 

KILL TESTPROG/BAS 

Deletes the named file from the first drive that contains it. 

KILL JOBF I LE/ I DY, PASSWORD : 1 

Deletes the named file from Drive 1 . The file has a password of password. 

KILL /BAS:0 

Deletes from Drive all files having the extension /bas. 
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LIB 

Display Library Commands 



LIB 



This command lists to the Display all the library commands. For help with a 
command, use help. 

Example 

LIB 



LIST 

List Contents of a File 



LIST fi7e(PRT,SL0W,ASCII) 

file is the file specification. 

prt tells trsdos to list to the Printer. If omitted, only the Video Display is 
used. 

slow tells trsdos to pause briefly after each record. If omitted, the listing is 
continuous. 

ascii tells trsdos to list the file in ascii format. If omitted, hexadecimal 
format is used. 



This routine lists the contents of a file. The listing shows both the hexadecimal 
contents and the ascii characters corresponding to each value. For values 
outside the range (X'20\ X'7F'), a period is displayed. 

Use the ascii option for text files and basic programs saved with the a option. 

Note: Only ascii codes xw-x'7F' are sent to the Printer. Bit 7 is always 
set to 0. 

During the listing, press (@D to pause, (ENTER) to continue, or ( BREA K) to exit. 
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Examples 

LIST DATA/TXT (ASCII ) 

Lists the contents of data/txt in ascii format. 

LIST FILE/A (SLOW) 

Lists the contents of file/a, pausing after each record. 

LIST PROGRAM/CMD (PRT) 

Lists the file program/cmd to the Printer. 



LOAD 

Load a Program File 



load file 

file is a file specification for a file created by trie dump command. 



This command loads a machine-language program file into memory. After the 
file is loaded, trsdos returns to the trsdos ready mode. 

You cannot use this command to load a basic program or any file created by 
basic. See the basic Reference Manual for instructions on loading basic 
programs. 

Note: The file must load into the user area (X'7000'-top). 

Examples 

LOAD PAYROLL / P T 1 

Sample Use 

Often several program modules must be loaded into memory for use by a master 
program. For example, suppose payroll/pti and payroll/pt2 are modules, and 
menu is the master program. Then you could use the commands: 

LOAD PAYROLL/PTI 
LOAD PAYROLL/ PT2 

to get modules into memory, and then type: MENU to load and execute menu. 
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MASTER 

Set Master Mead/1 ' W k Drive 






MASTER (DRIVE = a) 

a is the drive specification. If omitted Drive is set as the master drive. 



This command allows you to assign a specified drive as the Master Read or 
Write drive in the system. When searching for a file, trsdos will start with the 
master drive. 

If the file is not found on the specified drive, trsdos will continue searching on 
the next higher-numbered drive. 

Example 

After you enter the command: MASTER (DRIUE = 1 ) Drive 1 becomes the 
master drive. 



PATCH 

Change the Contents off a Disk Fie 



patch file (add = aaaa,nm = bh,zm = cc) 

file is the file specification 

add = aaa& specifies the address at which the data is found, aaaa is a four- 
digit hexadecimal number. 

find = bb specifies the string you wish io find (or compare to), bb is a 

hexadecimal sequence. 

chg = cc specifies the new coirtsnls foi the. byte(s). ce is a hexadecimal 
sequence. 

Note: This utility is for machine language programs only. 



55 






1 . B&2 "a TRQ-ft( 



nummi 



This command lets you make minor corrections in any disk file, provided that: 

1 . You know the existing contents and location of the data you want to change. 

2. You want to replace one string of code or data with another string of the 
same length. 

You can use patch to make minor changes to your own machine-language 
programs; you won't have to change the source code, re-assemble it, and re- 
create the file. 

Another application for patch is to allow you to implement any modifications to 
trsdos that may be supplied by Radio Shack. That way, you do not have to 
wait for a later release of the operating system. 

Sample Use 

Suppose you want to change seven bytes in a machine-language program file. 
First determine where the seven-byte sequence resides in ram when the program 
is loaded. Then make sure your replacement string is the same length as that 
of the original string. For example, you might write down the information 
as follows: 

File to be changed: vread 

Start address: X'5280' 

Sequence of code to be changed: xcd2D25E5 - 

Replacement code: X'00000009' 

Then you could use the following command: 

PATCH VREAD ( ADD=5280 »FIND=0CD2D25E5 >CHG=00000009 ) 



pause message 



message is the message to be displayed during the pause execution. This 
is optional. If omitted, pause will he displayed by itself. 
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This command is intended for use inside a do file so trsdos can print a message 
or reminder. 

To continue after the pause, trsdos prompts you with the message: 

PRESS (ENTER)- TO CONTINUE 

Example 

PAUSE INSERT DISKETTE «Z1 

trsdos displays pause, next the message and then prompts you to press ( ENTER) 
to continue execution. 

PAUSE 

PRESS < ENTER)- TO CONTINUE 

trsdos displays pause and then next prompts you to press (ENTER) to continue. 
See build and do for sample uses. 



Use or Change a Diskette's Master Password 



PR0T:«f(PW,L0CK) 

:d is an optional drive specification. If omitted, Drive is used. 

pw tells trsdos you want ie change the master password. 

lock tells trsdos to assign the master password to all unprotected user 
files, If omitted, the unprotected files remain unprotected. 



prot lets you use the master password to protect all unprotected files at once, or 
to change the master password. 

The master password will be needed to backup the diskette, so be sure to 
remember it! 

Note: The master password on the trsdos factory-release diskette is password. 
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PROT :0 (PW) 

Tells trsdos to change the master password on the Drive diskette, trsdos will 
prompt you first for the old master password, then for the new master password. 

PROT si (LOCK) 

Tells trsdos to assign the master password to all unprotected user files, trsdos 
will first prompt you for the master password. 



PURGE 
Delete Files 



purge :d (file-type) 

:d is the drive which contains the disk to be purged. 
file-type must be one of the following: 

sys AH System and User files (no Invisible) 

inv All Invisible and User files (Mo System) 
all AH files on disk (User, System, Invisible) 

If lie-type is o nlfteif, trsdos defaults to Use r files. 



This command allows quick deletion of files from a particular diskette. To use 
purge, you must know the diskette's master password, (trsdos System 
diskettes are supplied with the password password.) 

When the command is entered, trsdos will ask for the diskette's password. 
Type in up to eight characters. Press (ENTER ) if you typed fewer than eight 
characters. The System will then display user filenames one at a time, 
prompting you to kill or leave each file. 



PURGE : 1 

trsdos will purge user files from Drive 1 . This would include basic programs. 

PURGE :1 (I NO) 

trsdos will purge all invisible files in Drive 1. 
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Note: System diskettes contain some files which are not shown in any of the 
directory listings. You may delete these files with a special form of purge: 






purge* :d (file-type) 



The asterisk tells trsdos to ask you if you want to delete the System files. If 
you do delete them, the diskette becomes a data diskette and may only be used 
in Drive 1, 2 or 3. 

The other parts of this command are as explained previously. However, be sure 
to do the purge using Drive 1 , 2 or 3, since the diskette will become "non- 
system" during the purge. 



Change Where Program Loads Into Memory 



fslo file (add = aaaa) 

:. //Zeis the file specification..- ' ./ *■ * * '....*.. - 

add = aaaa specifies the new laac! addre ss aaaa is s four-digit hexadecimal 
number referring to m address in the oser memory aaaa must be in 
''"/"; : the user area, of ram. 



This command allows you to change the address at which the program loads into 
memory. It does not change the program itself. 

Note: This command may be useful in conjunction with dump. 

Example 

RELO PROGRAM/CMD (ADD=6578) 

trsdos will load the program program/cmd at the new memory address 
of 6578. 
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me osamme newname 
oldname is the old file name. 
newnatm is the new file name. 

The file name may iwW» a drive specification and a pa ;sword. 
The new file nanus should not include a drive specification or password. 



This command lets you rename a file or program. Only the name/extension 
is changed; the data in the file and its physical location on the diskette 
are unaffected. 

rename cannot be used to change a file's password protection. Use attrib 
to do that. 

rename also checks to see that the intended new name does not duplicate a 
filename currently on the same diskette. If it does, the command is cancelled 
and an error message is displayed. 

Examples 

RENAME MATHPAK MATHPAK/BAS 

Tells trsdos to add the extension to the filename. 

RENAME ABCDE/DAT ABCDEF/DAT 

Tells trsdos to change the filename only. 

RENAME PAYR0LL1/TXT.GSR PAYR0LL2/TXT 

Tells trsdos to change the filename; the password is retained automatically. 

RENAME FILE1:3 FILE2 

Tells trsdos to change the filename of the file on Drive 3. 
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Routing I/O Devices 



ROUTE (SOURCE = 33, DESTIN = bb) 

source -aa specifies the source m fisvice. 
destim = bb specifies the destination i/o dewice. 

aa and 66 may be any meaningful combination of the following two-letter 

abbreviations: ^ ^ 

do ■ (Display) 
pia {Printers 
kb (ifefboart) 
Ri (RS-232 input) 
ro ' (RS-232 Output) 

If the source and destination wjs5?3i! as ; omitted, trsdos resets i/o Bribers 
tc theii original i/o routes. The source anil destination devices mast loth lie 
output or both be input. 



This command allows you to route i/o devices automatically. For example, 
trsdos can route information from the Printer (PR) to the Display (DO). 

Note: route cannot be used in conjunction with the dual command. 



Examples 

ROUTE (SOURCE=PR*DESTIN=D0) 

trsdos will route your Printer output to the Display. 

ROUTE 

i/o drivers are returned to their original state. 

For further details on routing i/o see "Routing Input/Output" in the 
Model III Manual. 
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SETCOM ( OFF.WORD = 8, BAUD = A, STOP = C.PARITY = A BWlfe) 

off tarns rs-232-c off, - - , , 

word = a is the number of bit/byte desired, a must be either 5, 6, 7, or 8. 

depending on your needs. If omitted She word length is not changed. 

baud = b specifies the baud rate, b must be a decimal number between 50 
and 9600. if omitted, the baud rate is not changed. 

stop = c specifies the numbei of stop bits emisl be either I m 2. If 
omitted, stop bits are not change'd.. - 

parity = d determines whether the parity is odd, even, or none, d must be 3 
(none), 1 (odd), or 2 (even). If omitted, parity is not changed. 

. mot/e type either wait or nowait 

Options must be entered in the order stawst. 

IJ ail the 2p!isri are omitted, tosdos displays the Current rs-232-g settings. 



This command initializes rs-232-c communications via the serial channel. Before 
executing it, you should connect the communications device to the Model III. 

See the Model III Operation Manual for a description of rs-232-c signals used. 

See Using the RS-232-C Interface in the Model III Manual for further details. 

Examples 

SETCOH (WORD = 7»BAUD = 300»STOP=1 ,PARITY=3 tWAIT) 

This would set the rs-232-c to seven bit words, 300 baud, one stop bit, no parity, 
and place it in the wait mode. 

SETCOM 

The command without specifications will display the current settings. 

The following program will allow you to use your Computer as a terminal. For 
further information, refer to the Operation section of your Model III Operation 
Manual. 

Note: This program executes at 300 Baud. 
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5 DEFINT A-Z 

10 POKE 1G830, 

15 POKE 1G888. (5*lB)+5 

20 DEFUSRO = &H005A: REH 

40 X = USR0(0) 

60 DEFUSRI = &H0050 

B5 DEFUSR2 = &H0055 

70 CI = 1S872 

80 CO = 1G8B0 

90 ' CHECK FOR SERIAL IN 

110 X = USRK0) 

120 C* = CHR*(PEEK(CI) ) 

130 PRINT C* 

140 ' CHECK FOR KEYBOARD 

150 C* = INKEY$ 

1G0 IF C$ = "" THEN 110 

1G5 PRINT C*s 

170 POKE CO, ASC(C$) 

180 X = USR2(0) 

200 GOTO 110 



'INTEGER VARIABLE FOR SPEED 
'DON'T WAIT FOR SERIAL I/O 
'TX/RCU AT BAUD RATE 300 
SET UP CALL TO $RSINIT 



'CHARACTER INPUT BUFFER 

'CHARACTER OUTPUT BUFFER 

PUT 

'CALL *RSRCU 

'LOOK AT INPUT BUFFER 

'IF C = 0, NOTHING HAPPENS 

INPUT 

'NO KEY, SO GO CHECK SERIAL 

'SELF ECHO 

'PUT CHARACTER INTO OUTPUT BUFFER 

'QALL $RSTX 

'GO CHECK SERIAL INPUT 



Tape/Disk Transfer 



tape (s = source, d = destination) 

som'smiil destination are abbreviations for tS e storage devices to 

' • lis© usstf; ^ , 

■■■■'■■■■":■■'■ " t - Tape . / 

d Disk ' ; ^ 
. : R Random access memory 

Mote: tape can only be used with machine-language programs, basic 

programs must be CLOAoetf and csavescI. 



This command transfers z-80 machine-language programs from one storage 
device to another. The following transfers are possible: 

• Tape to disk 
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8 Disk to tape 




• Tape 


tO RAM 




Examples 




TAPE 


(S = T»0 = 


D 
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Starts a tape-to-disk transfer, trsdos will prompt you CASS?. Select the desired 
baud rate (H for high, L for low), trsdos will then prompt you to press (ENTER) 
when the recorder is ready to play to the Computer. When you press (ENTER) , the 
tape will begin loading. 

Note: If no asterisks flash, the recorder volume may need adjustment or the 
baud rate setting may be incorrect. 

trsdos will read the file name from the tape and use that name for the disk file. 
It will copy the program to the first write-enabled diskette, starting with the 
master drive (see master) . 

TAPE (S=D»D=T) 

Starts a disk-to-tape transfer, trsdos will prompt you for the desired cassette 
baud rate, then for the diskette file specification. Then it will tell you to press 
(ENTER) when the cassette recorder is ready to record from the Computer. 

TAPE <S=T>D=R) 

Starts a tape-to-RAM transfer, trsdos will prompt you for the cassette baud rate, 
and will tell you to press (EMTER) when the recorder is ready to play to the 
Computer. After loading the program, trsdos will begin execution at the 
transfer address specified on the tape. 



time hh:mm:ss 

hh:mm:ss specifies the hour hh, mwutj mm, mi second ss. 

Each must be a two-digit decimal number between tie following ranges: 
hh 0-23 

mm 0-59 

ss i-59 

If hh:mm:ss is giwen, trsdos resets the time. 

If hh:mm:ss is not giwen, trsdos displays fte current time. 
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This command lets you reset or display the time. 

Time uses a 24-hour clock. For example, 1:00 P.M. is displayed as 13:00. 

You initially set the time when trsdos is started up. After that, trsdos updates 
the time automatically, using its built-in clock. 

When you request the time, trsdos displays it in this format: 14:15:31 for 
2:15:31 P.M. 

Examples 

TIME 

Displays the current time. 

TIME 13:20:00 

Resets the time to 1:20:00 P.M. 

Note: If the clock is allowed to run past 23:59:59, it will re-cycle to zero, the 
date will be incremented, and the clock will continue to run. 



Write-Protect Via Software 



wp (drive =d) 



d specifies the disk drive to be protected. If omitted, all drives will be 

■ unprotested. 



Diskettes can be protected from being overwritten by this command. It is a 
software write-protect rather than a hardware write-protect (such as the write- 
protect tab on the diskette). 

Only one drive may be protected at a time. 

To unprotect a drive, making it accessible to writing, simply enter the command 
wp without options or with a different drive number specified. The wp command 
will not override a write-protect tab. 
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Examples 

WP (DRIME=1) 

trsdos will write-pro tect the disk in Drive 1 . 

WP 

trsdos will eliminate write-protection on all drives. 
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BACKUP 

Create an Exact Copy of an Original Disk 



backup -.source -.destination 

source specifies the drive containing the original diskette. If omitted. 
trsdos will prompt you for this information. 

-.destination specifies the drive containing the diskette to receive the copy, if 

. omitted, trsdos will prompt for It. 

•.source en& destination may reference line same drive. 



backup copies the contents of the source disk to the destination disk. This gives 
you a "safe" copy of the disk. Always keep an extra copy of data or programs 
you have stored on your disks. 

Note: Both source and destination diskettes must be write-enabled. 

trsdos will prompt you at each step after you type: BACKUP 

If you omitted the source/ destination-drive numbers, trsdos will begin with the 

prompts: SOURCE DRIVE NUMBER. 

Type in the number of the drive that contains the source diskette and press 

OTTER) . 

DESTINATION DRIVE NUMBER? 

Type in the number of the drive that will contain the destination diskette and 
press (ENTER) . 

SOURCE DISK MASTER PASSWORD? 

Type in the password assigned to your source diskette. 

DISK CONTAINS DATA* USE DISK OR NOT? 
Type in Y (Yes) or N (No). 
DO YOU WISH TO RE-FORMAT THE DISK? 
Type in Y (Yes) or N (No). 
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If you specified the source/destination drives, trsdos will request the 
password, skipping the first two steps. 

trsdos will then take charge of formatting and verifying the destination disk as 
well as letting you know if there are any errors or flawed tracks. 



CON VERT 

Model I to Model III File Conversion Utility 



CONVERT 



Model I formatted diskettes cannot be used in the Model III Disk System. 
However, the convert utility can read a Model I diskette and copy its non- 
system files onto a Model III trsdos diskette. This diskette may then be used 
normally in the Model III Disk System. The original Model I diskette may still 
be used in a Model I Disk System, since it is unchanged by convert. 

convert does not convert or change data; it converts the file storage format. 
For this reason, Model I Disk basic programs may require slight changes before 
they will run properly in the Model III Disk System. Model I machine-language 
programs may require major or minor changes before they will run in the Model 
III Disk System. You may make these changes on the Model I diskette before 
using convert, or on the Model III diskette containing the converted files. 

For hints on program conversion, see: 

• Technical Information in this manual 

8 Technical Information in the Model III Manual 

• The manual, Instructions for Converting Specified Model I Programs for use 
on trs-80 Model 111. 

Drive Usage 

In two-drive systems, the files must be copied onto a Model III system diskette 
in Drive 0; in three- or four-drive systems, the files may be copied onto a data 
diskette in Drive 1 , 2 or 3 . 

During the conversion process, the Model I diskette is referred to as the 
"source"; the Model III diskette, the "destination." The source diskette cannot 
be in the same drive as that of the destination diskette. 
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Password Protection 

convert is designed to preserve the password security of each file that it 
transfers. To accomplish this and still allow the copying of protected files, 
convert follows different procedures depending on the access and update 
passwords on each file. 

In the simplest case, a file has blank access and update passwords. The copied 
file will be given blank passwords. (If you have a Model I Disk System with 
trsdos 2.3, you may use the prot command to remove all passwords from all 
files. This will simplify the convert process. Do this on the Model I system 
before you attempt to convert to Model III.) 

In another case, the access and passwords are different. If the access password 
is blank and the update is not, then trsdos will prompt you for the update 
password. If you know the update password, type it in. The file will be copied 
with access and update passwords set to the old update password. If you don't 
know the update password, simply press ( ENTER) . The file will be copied with the 
access password set to blanks and the update password set to an unknown value. 

If the access and update passwords are not blank and they are not the same, 
trsdos will not copy the file, but will print the message, FILE SKIPPED, and 
continue with the next file in the source directory. 

Sample Use 

Get the Model I diskette ready. If you have a Model I Disk System with trsdos 
2.3, try to remove all passwords from all your files. This will prevent any 
problems with passwords. The password protection may be restored with the 
Model III attrib or prot commands after the conversion is complete. 

Using the Model III Disk System, you must always have a Model III trsdos 
diskette in Drive 0. trsdos ready should be displayed. Type: CONCERT CENTER) . 

The program will ask, SOURCE DRIVE?. Type in the number of the drive 
containing the Model I diskette, and press (ENTER) . Then the program will ask, 
DEST I NAT I ON DR I VE? . Type in the drive number and press CENTER) . In two- 
drive systems, you must use Drive as the destination. 

During the conversion process, the name of each file will be displayed as it is 
copied. If password information is needed, trsdos will prompt you for it. If 
you know the update password, type it in and press (ENTER) . The file will be 
copied and given the same update password. If you do not know the update 
password, simply press (ENTER) , in which case the file will be copied and given 
an unknown update password. 

If a file name on the source diskette is already used on the destination diskette, 
trsdos will print this message: FILE EXISTS, USE IT?. If you type Y, 
trsdos will copy the file. The previous contents of the Model III file will be 
lost. If you type N, trsdos will skip the file, and get the next one from the 
Model I diskette. 
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FORMAT :rf 



f/ Si-icjifies fe? disk d^vc which contains the diskette to te f!rro&*?ei. If d 
f? omitted, tbsdos will prompt you for Ms wwrjWierL 



This command lets you prepare data diskettes (either new or disks which contain 
undesired data or programs), leaving a maximum amount of space for your 
program and data files. 

Note: Data diskettes may only be used in Drives 1 , 2, and 3 except during a 

BACKUP Or FORMAT. 

format takes a blank (new or magnetically erased) diskette, records track/sector 
boundaries on it, then initializes it with and creates a directory. 

When format detects a non-blank diskette, it will display a warning message: 

DISK CONTAINS DATA* USE DISK OR NOT? 



Type Y (Yes) and press (ENTER) if you do want to reformat, N (No) and press 
( ENTER ) if you want to save the disk information. 

format will lock out any defective tracks to prevent data from being lost in 
these areas. 

If you begin to get read errors during access, reformat the disk. 



Example 

FORMAT si 

After you are prompted for DISKETTE NAME? and MASTER PASSWORD) 
TRSDOS will format Drive 1 . 
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Set Up for 50 Hz AC power (non-USA users) 



DO HERZ50 



starts the utility to change the system for 50 Hz operation, herzso is a do- 
file. 



This utility is provided for customers in areas where the ac power is 50 rather 
than 60 Hz. It should not be used by any other customers, herzso simply places 
a patch on the diskette that changes the clock speed for 50 Hz users. 

herzso is a DO-file that makes a change in the software of trsdos. Only the 
Drive diskette is changed. Be sure it is write-enabled before you start the do- 
file. Once the herzso change is done, it will remain in effect for that diskette. 

To perform the change, type: 

DO HER250 

Once the change has been made, you will need to reset the system to put the 
change into effect. This loads the new software into ram. 



lpc 



The lpc utility program allows trsdos to ignore multiple carriage return 
commands. Without lpc, a top-of-form (LPRiNTCHR$(i2» command will add an 
extra carriage return/line feed each time it is executed. Also, lpc masks the high 
bit of each data byte, allowing you to send certain intercepted codes to the 
printer. For instance, the basic statement lprint chr$( 140) will send code 140- 
128= 12 (lprintchr$(12» to the Printer. 
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The printers that require lpc are: 

Line Printer III (26-1156) 
Line Printer VI (26-1166) 
Daisy Wheel WP50 (26-1157) 
Qume Daisy Wheel (26-1 157A) 
Daisy Wheel II (26-1158) 

and all future printers. 

Printers that do not require lpc: 

26-1150, 1152, 1153, 1154, 1159, and the a version of lpiii (26-1 156A). 

You must load the lpc program before you load an application program. The 
easiest way to do this is to copy lpc onto your data/program diskette and then 
use the auto command to load lpc automatically each time you use the system. 
For instance, type: 



COPY LPC: i :0 ( ENTER) 

Then, to make lpc an auto command on the diskette, type: 



AUTO LPC/CMD (ENTER) 

Whenever you use your program diskette, lpc will automatically load into 
memory and you can use the program as usual. 

lpc locates into the highest available memory. There is no need to set MEMORY 
SIZE to protect lpc. It "hides" itself. However, you still need to set memory if 
required by your application program, lpc will be killed if the clear command 
is used. 

Warning: Once the lpc utility program is loaded and installed, you should not 
reload it except after a reset. Reloading re-installs the program and uses up more 
space each time! lpc will not execute if the Printer has been routed elsewhere. 
Also, if lpc has been executed and then the Printer is routed elsewhere, the 
original printer driver will regain control after the routing. 



MEMTEST 

Test Memory 



MEMTEST 



This program tests your Model Ill's memory (read only and random access). In 
trsdos ready, just type MEMTEST and press (ENTER) . 
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The program automatically tests all memory locations, no matter what memory 
size you have. First it checks read only memory (rom); if everything is okay, it 
automatically goes on and checks random access memory (ram). If all ram 
checks out okay, the program continues. 

If the program detects a rom or ram error, it will display a detailed message. 
Repeat the test to make sure it is a valid error condition. Write the message 
down and contact your nearest Radio Shack for assistance. 

Note: memtest changes the entire contents of ram. Before running it, be sure 
you have saved any valuable code you may have in ram. 

XFERSYS 
Transfer System Files 



XFERSYS 



xfersys lets you upgrade your version of Model III trsdos by copying all 
system files from a new release diskette (source) onto a previously released 
diskette (destination) (i.e., version 1 . 2 to version 1 . 3 , etc . ) . 

System files which already exist on the destination diskette are replaced by those 
from the source diskette. Files which do not exist on the destination diskette are 
added. User files (program and data) are unaffected. 

Steps to upgrade a diskette 

Make backup copies of all diskettes to be upgraded. This is an important 
precautionary step. These backup copies should be kept until the upgrading 
process is complete and confirmed. 

Note: Both source and destination diskettes must be write-enabled. 

Insert the new release of trsdos into Drive and press the reset button. Then 
type XFERSYS CENTEH) . 

After the program heading appears, trsdos will prompt you with DISKETTE TO 
CONVE RT READY IN DRIVE 1 ( Y / )?. Type Y (yes) or (quit) and press 

(ENTER) . 

The upgrading process will then take place. When the process is complete, 
trsdos will tell you so and take you back to trsdos ready. 

Note: If an error occurs, including your trying to upgrade a non-system diskette, 
the operation will be cancelled and take you back to trsdos ready. 
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Contents of This Section: 

Disk Organization 

File Structure 

System Routines for Assembly i/o 

Data/Device Control Blocks 

Physical and Logical Records 

Fundamental trsdos i/o Calls 

Additional Routines and Storage Addresses 
trsdos Error Codes/Messages 

Disk Organization 

Each trsdos system diskette contains a trsdos system, a utility command 
library, and a file directory. 

Each diskette is single-sided and has 40 tracks of information. Each track 
contains 18 sectors of 256 bytes each. 

Normally, data read/ write operations may be initiated only at sector boundaries, 
and must consist of exactly 256 bytes. However, trsdos allows the user to have 
maximum flexibility with minimal effort by automatically blocking and de- 
blocking all file accesses to user-specified logical record lengths, even if this 
requires "spanning" of two sectors. 

The system disk file structure allows maximum use of disk file space by 

automatically segmenting files across a diskette in several small pieces. These 

pieces are correlated into one logically contiguous file by the system without 

your needing to know the physical file location. This structure eliminates time- A v, 

consuming disk-packing operations. ^ v4? 

File Structure *i Jr 

A trsdos file is composed of one or more segments of storage space. Each £, ^ 

segment consists of from one to 32 physically contiguous granules of storage. A ^ Ji 

granule is the minimum allocatable unit of storage, and consists of three sectors ^f ^p 

(768 bytes). ^ 

Since a file is always lengthened by granules, a small amount of free storage is v 

generally present at the end of every file. This free storage allows minor file 
additions to be made in space which is physically contiguous to the file. 

Every time a disk file is extended (either initialized or lengthened), extra 
granules may be allocated to that file, depending on the file's accumulated 
length, diskette space, saturation, etc. These extra granules, along with all 
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granules after the one containing the file's eof mark, are recovered and returned 
to the system when the file is closed. 

A TRSDOS ile 

FILE: 



LRN1 


LRN2 


LRN3 


LRNN 


EOF 


EXTENT 1 


EXTENT 2 



SEGMENT: 



GRANULE 1 


GRANULE 2 




GRANULE 32 



GRANULE: 



SECTOR X 



SECTOR X + 1 



SECTOR X + 



2 | 



BYTE1 


BYTE 2 


BYTES 




BYTE 256 



SECTOR: 

LRN: Logical Record Number, used to specify an individual, user-defined 
logical record. Such a logical record is the smallest unit of 
information which can be addressed during disk input/output (a 
physical record is the unit which is actually read from or written to 
disk). 

File: A group of logical records; the largest unit of information which can 

be addressed by a trsdos command. 

Sector: A physical record, composed of 256 contiguous bytes. 

Granule: The minimum allocatable unit of storage for any file. 

Extent: One contiguous allocation of granules. 

System Routines for Assembly-Language I/O 

This information is provided for customers who wish to write their own 
assembly level i/o routines. An explanation of the calling sequence and 
parameters for each necessary i/o routine is given. A knowledge of z-80 machine 
code is assumed. 

The following notations are standard in this section: 

(HL) = xxxx Registers hl contain the address of (point to) xxxx in machine 
format. (If address of xxxx = 34B2H then the values in the 
registers are: h = 34; l = B2). Other register pairs will also be 
indicated this way. 

a = xx Register a contains the numeric value of xx in binary form. 

Register a is used to return the trsdos error code for i/o calls. 
A complete list of error codes and their meanings appears at 
the end of this chapter. Other registers will also be indicated 
this way. 
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IBS DISK SYSTEM 



Z = OK 



Zero flag is set (OK) if successful return from the system 
routines. 



X nnnn 
or nnnnn 



Hard ram address in hex notation (e.g., 402D is X'402D'). 



lrl 



BUFFER 



Logical Record Length, 1-255 bytes only. You can define 
records any length you wish up to 255 bytes maximum. A 
length of zero is a special case for physical records only, and 
indicates the lrl = 256 bytes. 

256 user-designated bytes in ram for trsdos to read sectors 
from or write sectors into. If lrl = o, this area is the 
responsibility of the user to manage before and after i/o. trsdos 
manages this area if lrl is between 1 and 255 bytes. Do not 
alter this area when using logical record processing. 



UREC 



(User Record) The address of the contiguous ram byte-string 
assigned by the user as his logical record area. Its length must 
be equal to lrl. It is a different area from buffer. 



lsb/msb Least-significant byte followed by most significant byte. This is 

the standard z-80 format for addresses. 



$name 



The "$" is prefixed to all system locations and call routines, so 
they will not be confused with trsdos commands or utilities. 
For example, sopen. 



DCB before $OPEN and after $CLOSE 

The dcb (device control block) is defined as 50 contiguous bytes of ram 
designated by the user. Before $open and after $close, it is a left-justified, 
compressed (no spaces) ascii string, as in a standard trsdos filespec. The string 
is terminated with a carriage return. 













8 














16 










24 




1 
f i 


1 

1 e 

1 


n 


a 


m 


e 


/ 


e 


X 


t 


P 

i 


a 


s s 


w 





r 


I 
d 

i 


I I 

d $ 
I I 





Notes: /ext, .password, and :d are optional. 
$ stands for a carriage return (X'OD') 
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DCB while $OPEN 



Address 


Length 


Explanation 


DCB + O 


3 


Reserved 


+ 3 


2 


Physical Buffer address (lsb/msb) 


+ 5 




Offset to delimiter at end of current record 


+ 6 




File drive number residence 


+ 7 




Reserved 


+ 8 




eof offset of last delimiter in last physical record 


+ 9 




lrl (logical record length) 


+ 10 


2 


nrn (next record # — $open sets = xwoo' — lsb/msb) 


+ 12 


2 


ern (ending record # — (last in file) lsb/msb) 


+ 14 


50 


Reserved 



NRN Next Record Number defines which record is to be read or written by the 
next system call for $read or $write. It is automatically incremented by one 
after each system call. In order to process random files, use the $posn call to 
direct trsdos to the record you wish to transfer next. 

ERN Ending Record Number is the last record number currently in the file. It 
is put into the directory at SCLOSE time, so if it is expected to be correct, the user 
must close his files after adding records to a file. This value may also be used to 
position to end of file so that new records may be added to the end of the file. To 
position to the end of file use a call to sposn with a record number of ern + i. 
$posn is described later. 

Physical and Logical Records in TRSDOS 

A physical record is defined as one sector of disk. One sector of disk contains 
256 user data bytes. The artificial term "granule" is defined to be 3 sectors of 
disk space. There are 6 granules on each of the 40 tracks on the disk. A granule 
is the least amount of space allocated by trsdos. For programming purposes, 
the physical records in a file are numbered from to N. The largest record 
number (N) in a file will then be 3 times the number of granules allocated minus 
one ((3*G) - 1). All trsdos granule allocations are made as needed at the time 
of write, not when the file is created. 



Bytes 



Sectors 



Granules 



Tracks 



Disk 



256 

768 

4608 

184320 



3 1 — 

18 6 1 

720 240 40 

Disk Space Table: For each 5 l A" Disk Drive 



A logical record is defined by the user of tRsdos. It may be anywhere from 1 to 
255 bytes in length. Once a file is opened with a specific lrl (Logical Record 
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Length), the length is fixed until the file is closed. To change a file's lrl, you 
must close it and re-OPEN it with the new lrl. 

Each opening of the file sets a single, fixed record-length, trsdos will "block" 
logical records into (or from) one physical record for maximum space utilization 
on the disk. 

Blocking is putting more than one logical record into one physical record. For 
instance, four 64-byte logical records will fit into one 256-byte physical record. 
A logical record may be broken into two parts by trsdos in order to fill the last 
portion of one physical record entirely before beginning to use the next physical 
record (i.e. records are spanned). This occurs when the physical record length is 
not an even multiple of the logical record length. 

If the user wishes to do his own blocking, he may specify a logical record length 
of bytes at the time of init/open and must himself manage the contents of the 
physical record buffer area of 256 bytes, trsdos will not move a logical record 
for the user if lrl = 0; in this particular case it will only read/write the physical 
record to/from the buffer. Once control is shifted to your program, you will have 
about 20 bytes of stack size left. 

Fundamental TRSDOS I/O Calls 

There are 17 fundamental trsdos routines involved in handling file i/o. These 
are: 

$BACKSPACE $POSN 

$CLOSE $PUTEXT 

$DIVIDE $RAMDIR 

$DMULT $READ 

$FILPTR $REWIND 

$INIT $SYNTAX 

SKILL $VERF 

$OPEN $WRITE 
$POSEOF 

The detailed calling sequences and discussions for each of these routines follow. 
Note that all of these system calls use register f and do not restore its value 
before return. In order to apply this data properly, you should read through all of 
these descriptions and clear up all of the points that are not obvious to you by 
using other reference materials. If you are successful in doing this you will find 
that trsdos is a workable tool for your programming ideas. 



$INIT — 17440/X'4420' 



$init is provided as an entry point to trsdos which will create a new file entry 
in the directory and open the dcb for this file. $init scans the directory for the 
filespec name given in the dcb. If the filespec name is found, $init simply opens 
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the file for use. If the name is not found, a new file is created with the filespec 
name. 

Entry Conditions 

(HL) = buffer (see beginning of this section for notation) 
(DE) = DCB 
B = LRL 
CALL $INIT 

Exit Conditions 

iy = changed 

z = OK 

c carry flag is on if a new file was created 

a = trsdos error code. (Error codes listed at end of this chapter) 

$OPEN — 17444/X ? 4424 ? 

$open provides a way to open the dcb of a file which already exists in the 
directory. The dcb must contain the filespec of the file to be opened before entry 
to $OPEN. 

Entry Conditions 

(HL) = BUFFER 
(DE) = DCB 
B = LRL 
CALL $OPEN 

Exit Conditions 

Z = OK 

z = if file does not exist. 
a = trsdos error code. 
iy = changed 



$POSN— 17474/X ? 4442' 

$posn positions a file to read or write a randomly selected logical record. Since 
it deals with logical records, the proper computation is done to locate which 
physical record(s) contain the data. Following a $posn with a $read or $write 
will transfer the record to/from ram. 
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Note that positioning to logical record zero sets the file to read the first logical 
record in the file. To position to end of file in order to add new records onto the 
end, use the record number ern + 1 . 

Entry Conditions 

(DE) = dcb (must have been opened previously) 
bc = Logical record number to position for. 

CALL SPOSN 

Exit Conditions 

Z = OK 

a = trsdos error code . 

$READ— 17462/X'4436 ? 

If lrlo, $read transfers the logical record whose number is in the dcb as nrn 
into the ram area addressed as urec for the length lrl as defined at open time. 
The record comes from "buffer" defined at open time. If trsdos must read a 
new physical record to satisfy the request, it will do so. "Spanned" logical 
records will be re-assembled as necessary. $read automatically increments nrn 
by 1 in the dcb after the transfer is completed. $init/open set nrn^x'oooo' in 
order to read the first record with the first read. 

If lrl = o, $read transfers one physical record into buffer, defined at open 
time, from the disk file. Registers hl are ignored. $read increments nrn as 
above. 



(HL) = urec if lrl is not zero. Unused if lrl = o. 
(DE) = dcb 
CALL SREAD 

Exit Conditions 

Z = OK 

a = trsdos error code. (eof = x*ic or x'id*) 
(see errors 28,29 for eof or nrf) 

$WRITE^ 17465/X ? 4439' 

If lrlo, swrite transfers the one logical record from the ram area addressed 
as urec for the length lrl as defined at open time. The record goes into the 
buffer which was defined at open time. If trsdos must write a physical record 
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in order to satisfy the request, it will do so. "Spanning" will be handled by 
trsdos as necessary. At $init $open time the dcb value of nrn is set to X'oooo' 
so that the first record will be written. After each logical record is transferred, 
the nrn value in the dcb will be incremented by 1 . 

If lrl = o, $write transfers one physical record from buffer into the disk file 
using the nrn in the dcb. buffer is defined at $init/open time only. The dcb 
value nrn is updated as above, after the write. 

Entry Conditions 

(HL) = urec if lrl is not zero. Unused if lrl = o 
de = dcb 
call $wr1te 

Exit Conditions 

Z = OK 

a = trsdos error code. 



-17468/X'443C 

The only difference between $verf and swrite is that $verf writes one physical 
record to disk and then reads it back into a special trsdos ram area not defined 
by the user. This special area and the original write buffer are then compared 
byte by byte to assure that the record was successfully written. 



Entry Conditions 

(HL) = Same as swrite above. 
(DE) = dcb 
CALL SVERF 



Exit Conditions 

Z = OK 

a = trsdos error code. 



$PUTEXT— 17483/X ? 444B ? 

This routine will add an extension to a filename if an extension does not already 
exist. An extension to a filename may be useful for identifying the type of data 
in the file. 
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Entry Conditions 

(DE) = DCB 

(HL) = The extension to be added to the file 

CALL SPUTEXT 

Exit Conditions 

None 

$BKSPC — 17477/X'444§ 9 

This routine positions the file record pointer to the previous record. 

Entry Conditions 

(DE) = DCB 
CALL $BKSPC 

Exit Conditions 

z = Valid position 

nz = Invalid position in file 

$REW1NB — 17471/X 9 443F 9 

Point to the beginning of the file. This routine positions the file pointer to the 
first record in the file. This is useful when the same file must be processed more 
than once. 

Entry Conditions 

(DE) = DCB 

Exit Conditions 

z = Good file specification 
nz = Bad file specification 

CALL SREWIND 



$POSEOF — 17480/X 9 4448' 

Point to the end of file. This routine positions the file pointer to the last record in 
the file. This may be used to extend a sequential access file. 
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Entry Conditions 

(DE) = DCB 
CALL SPOSEOF 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$SYNTAX— 17436/X 9 441C 

Move a file specification to dcb. This routine takes a file specification and 
checks it for validity and moves it to a dcb so that the file may be opened. 

Entry Conditions 
(HL) = Filename 

(DE) = DCB 
CALL SSYNTAX 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$DIVIDE — 17489/X'445 1 ' 

The divide routine takes a 16-bit dividend and an eight-bit divisor. After 
division, the quotient replaces the 16-bit dividend and the remainder replaces the 
eight-bit divisor. 

Entry Conditions 

hl = Dividend 
A = Divisor 

CALL SDIVIDE 



Exit Conditions 

HL = Quotient 

a = Remainder (0 indicates no remainder). 
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$OMULT— 17486/X 9 444E' 

The multiply routine uses a 16-bit multiplicand and an eight-bit multiplier. After 
multiplication takes place, the product replaces the 16-bit multiplicand. 

Entry Conditions 

hl = Multiplicand 
A = Multiplier 

CALL SDMULT 



Exit Conditions 

H = High order byte 
L = Middle order byte 
a = Low order byte 

H L 



High Middle Low 



IIR^17©40/X 9 429!F 

This routine allows you to examine a diskette directory (one entry or the entire 
directory) or the diskette's free space. The information is written into a user 
specified ram buffer. 

Only non-system files will be included in the ram directory. 



Entry Conditions 



hl = ram Buffer. If c = 0, size = 1761 [max #*22+ 1]. If c= 1 to 96, 

size = 22. If c = 255, size = 64. 
b = Specified drive number 
c = Function switch: 

Contents of C Results 

Gets entire directory into ram. (See ram Directory Format). 

1-96 Gets one specified directory record into ram, if it exists. (See 

ram Directory Format) . 

255 Gets free-space information (See ram Directory Format). 

call sramdir 

Exit Conditions 

nz = Error occurred. 

z = No error. (HL) = directory or free-space information. 
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RAM Directory Format 

The directory is made up of records, one per file. All values are hexadecimal. 
Each record placed in user ram is in the following format: 

Byte Number Contents 

0-14 filename! ext:d (left-justified followed by spaces) 

15 Protection Level, binary 0-6 

16 Byte EOF, binary 0-255 

17 Logical record length, binary 0-255 
18-19 Last sector number in file, binary lsb, msb 
20-21 Number of Granules allocated clsb.msb) binary 

22 " + " (marks the end of directory list after entire directory.) 

Free Space Message Format 

***nnnnn Free Granules*** 

Where nnnnn is a decimal number. The entire message is Ascn-coded. 

$FILPTR— 17037/X'428B ? 

This routine provides information on any user file that is currently open. It 
enables you to obtain the drive number and the logical file number for any file 
and should be used in conjunction with sramdir. 

Entry Condition 

(DE) = Data Control Block (dcb) defined when file was opened. 

CALL $FILPTR 

Exit Conditions 

nz = Error occurred. 

z = No error. The following registers are set up: 
b = Which drive contains the file (0,1,2, or 3). 
c = Logical file number (1-96) 

Note: This operates with user files only. 

$CLOSE— 17448/X 9 4428 ? 

$close closes a file from the last processing done. It is very important to do 
a $close on every file opened before the program ends. If you do not close 
a file, the directory entry for this file is incorrect if any new records have been 
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written into the file. Other cases are not given here, but it is very important to 
trsdos that all of the "housekeeping" be complete for file management. 

Entry Conditions 

(DE) = DCB 
CALL SCLOSE 

Exit Conditions 

Z = OK 

a = trsdos error code. 



$JKILL — 174§2/X 9 442C 

skill deletes the directory entry for a file and releases the disk storage. The file 
may be open or closed; skill will operate in either case. 

Entry Conditions 

(DE) = DCB 
CALL SKILL 



Exit Conditions 

Z = OK 

a = trsdos error code. 



Additional Routines and Storage Addresses 
$JP2D08 — 16429/X'402D ? 

This routine transfers control to trsdos ready. 

Entry Conditions 

JP SJP2DOS 

Exit Conditions 

None 
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$OATE— 12339/X 9 3(B3 9 
$TIME— 12342/X ? 3CI36 9 

These routines return the date and time in ascii format: 

Date: mm/dd/yy 
Time: hh/mm/ss 

Entry Conditions 

(HL) = Eight-byte buffer to receive the date/time text 

CALL SDATE 

CALL $TIME 

Exit Conditions 

(HL) = Date or time text 



IATLOC — 16922/X 9 421 A 9 
$TIMLOC — 169 19/X 9 4217 9 



These locations store the date and time in binary format: 

SDATLOC (Three bytes): yy dd yy 
STIMLOC (Three bytes): ss mm hh 

$EMROSP— 17417/X 9 44t)9 ? 

This routine displays a trsdos error message determined by the contents of the 
accumulator (A). This register contains an error code (0 = no error) after 
completion of any system routine. 

Entry Conditions 

A = trsdos error code (see Table at the end of this section). In a trsdos error 
code, bits 6 and 7 are normally reset (off). So $errdsp interprets them as 
controls. 



Bit # 

7 

6 

CALL SERRDSP 

wmmmmsmem 



Set 

Return to caller upon 
completion 

Give detailed error message 



Not Set (Normal 
Condition) 

Return to trsdos upon 
completion 

Give error number only 
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Exit Conditions 

None 

Sample Use 

CALL $SYSRTN 5 ANY SYSTEM ROUTINE 
JR ZfOKGO i CHECK FOR ERROR 

! THE FOLLOWING INSTRUCTION SETS BIT 8 (DETAILED 

! ERROR MESSAGE) AND BIT 7 (RETURN TO CALLER AFTER 

i DISPLAYING MESSAGE 

OR C0H 5 BINARY 11000000 

CALL $ERRDSP 5 NOW CALL ERROR DISPLAY 

» CONTINUE HERE UPON RETURN FROM ERROR DISPLAY 

J YOUR ERROR HANDLER MAY GO HERE 



OKGO 5 CONTINUATION AFTER $SYSRTN WITH NO ERROR 



$DSFMR— 17433/X 9 4419 ? 

This command displays the directory listing of all non-protected user files in a 
specified drive. 



Entry Conditions 



(X'427r) = Ascn-coded drive number "0," "1," "2," or "3" 

CALL SDSPDIR 



All registers are changed. 



IOS— 17049/X 9 4299 ? 

This routine executes a trsdos command and returns to trsdos ready. 

Entry Conditions 

(HL) = Text of trsdos command, terminated by X'OD.' 

JP SCOMDOS 

Exit Conditions 

None 
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$CMOOOS— 17052/X ? 429C 9 

This routine executes a trsdos command and returns to the caller. 

Entry Conditions 

(HL) = Text of trsdos command, terminated by X'OD; 

Exit Conditions 

All registers are changed. 

Caution: trsdos commands will overlay ram up to X'6FFF.' 

$CMDIXT^ 16933/X 9 4225 ? 

This is the start address of a buffer containing the last command line entered 
under trsdos ready. Using this buffer, your program may recover parameters 
that were included in the last command line. 

For example, given a program named editor/cmd, we want the operator to 
select an input file name when the program is loaded and executed from trsdos 
ready: 

trsdos ready 
editor myfile 

The program, editor, can recover the name of the file in the scmdtxt buffer. 

Note: On entry to a program, (HL) = First non-blank character following the 
program name. 



;NB^17425/X 9 441F 

This storage location contains the highest address available. It is normally the 
same as the physical end of ram, but you may change it for special purposes. 

The address is in lsb, msb sequence. 



J^j™iifeiiiMii liMilli 
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TRSDOS Error Codes/Messages 

No Error Found 

1 CRC Error During Disk I/O 

2 Disk Drive Not In System 

3 Lost Data During Disk I/O 

4 CRC Error During Disk I/O 

5 Disk Sector Not Found 

6 Disk Drive Hardware Fault 

7 "Undefined Error Code** 

8 Disk Drive Not Ready 

9 Illegal I/O Attempt 

10 Required Command Parameter Not Found 

11 Illegal Command Parameter 

1 2 Time Out On Disk Drive 

1 3 I/O Attempt To Non-System Disk 

14 Write Fault On Disk I/O 

15 Write Protected Disk 

16 Illegal Logical File Number 

17 Directory Read Error 

18 Directory Write Error 

19 Invalid File Name 

20 GAT Read Error 

21 GAT Write Error 

22 HIT Read Error 

23 HIT Write Error 

24 File Not Found 

25 File Access Denied Due to Password Protection 

26 Directory Space Full 

27 Disk Space Full 

28 Attempt to Read Past EOF 

29 Attempt to Read Outside of File Limits 

30 No More Extents Available 

31 Program Not Found 

32 Invalid Drive Number 

33 "Undefined Error Code" 

34 Attempt to Use Non-program File as a Program 

35 Memory Fault During Program Load 

36 "Undefined Error Code" 

37 File Access Denied Due to Password Protection 

38 I/O Attempt to Unopen File 

39 Invalid Command Parameter 

40 File Already In Directory 

41 Attempt to Open File Already Open 
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Introduction 

Start-Up 

Under trsdos ready, type: 



BASIC CENTER) 

trsdos will load basic and begin the "initialization dialog." 

If you want to recover a Disk basic program after returning to trsdos for a dir 
or other trsdos command, use this command under trsdos ready: 



BASIC * CENTER ) 

You will go directly to Basic's ready mode without any initialization dialog. If 
you had a program in memory, it should still be there. You may not be able to 
run the program. To be safe, you should immediately save the program, go to 
trsdos, then start basic again (no asterisk). 

Note: If you have overlaid user memory while in trsdos, your program will be 
erased. In such a case, you should not restart basic, but should use the normal 
basic start-up procedure. 



Initialization 

When you start Disk basic, you are first asked, HON MANY FILES?. This lets 
you specify the maximum number of files that will be "open" or in use at once. 
(See o pen.) Type in an appropriate number and press CENTER) , or simply press 
CENTER) and basic will provide for three files. 

For example, if your program requires one input file and one output file, you 
should ask for two files. 

Note: Normally, basic will give all your data files a record length of 256. 
(See File Access Techniques.) If you wish to set the record length of each file 
individually, use the suffix v for "Variable" after the number of files. 
For example, 



HOW MANY FILES? 3M CENTER) 

tells basic to give you three lie-buffers, and to let you set the record length of 
each file when that file is first opened. 

Note: Disk basic automatically creates a buffer for loading, saving, and 
merging basic programs. This buffer exists in ram below any data file buffers 
you may request. It is always available for program i/o, regardless of how you 
answer the files? question. 
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After you answer the files question, basic will ask: MEMORY SIZE? Simply 
press (ENTER) without typing a number. You will then have the maximum amount 
of ram available for use by basic. 

If you will want to load and use machine-language programs or routines, you 
will have to protect your basic memory from these machine-language programs. 

In such a case, respond with the highest memory address (in decimal form) you 
want basic to use for storing and executing your basic programs. Addresses 
above the number you specify will then be protected from use by basic. 

Example: 



MEMORY SIZE? 32000 dMIER) 

causes basic to protect addresses above 32000. If you have 16K of ram, this 
means that you'll have 32767-32000 = 767 bytes protected for storing your 
machine-language routines. 

After you answer the MEMORY SIZE? question, Disk basic will display the 
following information: 

1 . Which version of Disk basic you are using 

2. Copyright information 

3. The number of free bytes available 

4. The number of concurrent files you have requested. 

To exit from Disk basic and return to the trsdos ready mode, type: 



CMD"S" (ESTER) 

This results in a normal return to trsdos, without re-initialization of the system. 
You may recover your program if you haven't changed user memory while in 
trsdos. Use basic *. 
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Enhancements to Mode! W BASIC 

Disk basic adds many features which are not disk-related. They are listed below 
along with abbreviated descriptions. Detailed descriptions follow in alphabetical 
order. 



&H 

&o 
Abbreviations 

CMD"A" 

CMD"B" 

CMD"C" 

CMD"D" 

CMD"E" 

CMD'T' 

CMD"J" 

CMD"L" 

CMD"0" 

CMD'T" 

CMD"R" 

CMD"S" 

CMD'T" 

CMD"X" 

CMD"Z" 
DEFFN 
DEF USR 

INSTR 
LINE INPUT 
MID$ = 

NAME 
USRrt 



Hexadecimal-constant prefix 

Octal-constant prefix 

Many commands have abbreviations 

Return to trsdos with error message 

Enable/Disable (BREAK) 

Delete spaces and remarks from a program (compression) 

Display directory for specified drive 

Display previous trsdos error 

Return a command to trsdos 

Convert calendar date 

Load z-80 subroutine or program file into ram 

Alphabetizes (sorts) a string array only 

Check printer status 

Start real-time clock display 

Normal return to trsdos (jump to exit routine) 

Turn off real-time clock display 

Cross-reference of reserved words, string variables, or 

strings in a program 

Duplicate output to Display and Printer 

Define basic- statement function 

Define the entry point for an external machine-language 

routine 

Instring function; find the substring in the target string 

Input a line from keyboard 

Replace portion of the target string (used on left of equals 

sign) 

Renumber a program in ram 

Call external routine (« = 0,1,2, ... ,9) 



&H and &O (hex and octal constants) 

Often it is convenient to use hexadecimal (base 16) or octal (base 8) constants 
rather than their decimal counterparts. For example, memory addresses and byte 
values are easier to manipulate in hex form. &h and &o let you introduce such 
constants into your program. 

&h and &o are used as prefixes for the numerals that immediately follow them: 
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tMdddd 



dddd is a 1 to 4 digit sequence composed of Hexadecimal numerals 
0,1,...9,A,B.....F. 

&oddddd 

ddddd is a sequence of octal numerals 0,1, ...J and &oddddd< = 177777 
decimal. 

Note: The o can be omitted from the prefix &o. Therefore &oddddd=.&ddddd. 



The constants always represent signed integers. Therefore any hex number 
greater than &H7FFF, or any octal number greater than &.QI1111, will be 
interpreted as a negative quantity. The following table illustrates this: 



Octal 



Hex 



Decimal 



&1 


&H1 


1 


&2 


&H2 


2 


&77777 


&H7FFF 


32767 


& 100000 


&H8000 


-32768 


& 100001 


&H8001 


-32767 


&1 00002 


&H8002 


-32766 


& 177776 


&HFFFE 


-2 


& 177777 


&HFFFF 


-1 



Hex and octal constants cannot be typed in as responses to an input prompt 
or be contained in a data statement. Often the hex or octal constant must be 
enclosed in parentheses to prevent a syntax error from occurring. 

Examples 

PRINT &H5200* &O51000 

prints the decimal equivalent of the two constants (both equal 20992). 

POKE &H3C00, 42 

puts decimal 42 (ascii code for an asterisk) into video memory address hex 

3C00. 
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Mode! Ill Disk 


BASIC Abbreviations 


Abbreviation 


Meaning 


® 


List Previous Program Line 


© 


List Next Program Line 


CD 


List Current Program Line 


CD 


Edit Current Program Line 


(SHIFT) © 


List First Program Line 


(SHIFT) © © 


List Last Program Line 


ucx 


List Program Line xx 


EXX 


Edit Program Line xx 


DXX 


Delete Program Line xx 


AXXX,XXXX 


Automatic Line Numbering Beginning at Line xxx, 




Incrementing by xxxx. 



,& A 99 



Return to TRSDOS 



CMD"A' : 



This command allows you to return to trsdos with an error message: 
OPERATION ABORTED 

Sample Use 

After an input/output error occurs in a basic program, you might want to exit to 
trsdos and print a message. 

CMD"A" 

the following will be displayed: 

OPERATION ABORTED 
TRSDOS READY 

4t»ttt*4<4*t*4*»tft 
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CMD "B" 

Enable/Disable BREAK Key 



cmd"B", 'switch' 



switch is either on or off. switch must be enclosed in quotation marks. 



This command enables or disables the (BREAK) key. While the function is "off," 
the (BREAK) key will be ignored except during cassette or printer output or during 
serial input/output. 



The (BREAK) key will remain disabled even after the program has ended. To 
enable the (BREAK) key, use the cmd"B","ON" command. Returning to trsdos 
via the cmd"S" or cmd'T' commands will also enable the (BREAK) key. 

Examples 

CMD"B" »"0FF" 



Disables the (BREAK ) key. 

CMD"B" »"0N" 

Returns the (BREAK) key to its normal function. 

CMD "C" 

Compress Program 



crvtD '%■', options 



options may be either r (delete remarks) or s {delete spaces). If both 
options are omitted, remarks and spaces are deleted. If only one is 
owittec?, only the specified action is lakes. 



This command allows you to compress a program so that it requires less 
ram and less storage space on diskette. You can elect to remove all remark 
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statements (beginning with rem or ') or to delete all spaces between basic 
keywords. Spaces inside quotes will not be deleted. 

Example 

Your program reads as follows: 

850 RESTORE: ON ERROR GOTO 800 'DOG PROGRAM 

8B0 READ COMPANY* 'PET STORE 

870 PRINT RIGHT$(C0MPANY*»2> >: GOTO 860 

880 END 

If you want to delete the Remarks (lines 850 and 860), type in the command: 

CMD"C" .R 

and the program will now read: 

850 RESTORE: ON ERROR GOTO 800 

860 READ COMPANY* 

870 PRINT RIGHT*(C0MPANY*»2) »:G0T0 860 

880 END 

If you then wanted to delete the spaces, type in: 

CMD"C" ,S 

and the program would read: 

850 RESTORE : ONERRORGOTO800 

860 READCOMPANY* 

870 PRINTRIGHT*(C0MPANY*»2) »:GOTO8S0 

880 END 

You could obtain the same results by typing: 

CMD"C" 

Note: Always provide the closing quotes on string literals in your basic 
program. Otherwise cmd"C" may not function properly. For example, in 

10 PRINT "THIS IS A TEST" 

the second quote should be used even though omitting it will not cause an error. 

CMD"D" 

Display the Directory of a Specified Drive 



mo"o:d" / "; 

d is the drive specification 
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By entering the command cmd"d:<5P' , you can obtain a specified diskette's 
directory from basic without returning to trsdos. Only unprotected, visible 
files will be displayed. The drive specification is not optional and must be 
specified for all drives, including Drive 0. 

Example 

If you type in the command: 

CMD"D:1" 

the directory for Drive 1 will be displayed. 



Display Previous TRSDOS error 



CMD"E" 



This command displays the last trsdos error message. If no errors have 
occurred prior to the command, the message NO ERROR FOUND will be 
displayed. 

Example 

If you have a two-drive system (0 and 1) and you type: 

SAME "PROGRAM: 3" 

Disk basic will return a D I SK I/O ERROR . To find out what kind of I/O error 
occurred, type: CMD " E " ( ENTER) and Disk basic will return with DISK DR I VE 
NOT IN SYSTEM. 

CMD"I" 

Execute TRSDOS Commands from Disk BASH 



mo"\", command '' , , ' 

command is a string expression containing a trsdos command or a z-80 
program file name. If it is a string constant, it must be enclosed in 

quotes. 



98 



You may execute trsdos commands directly from basic by using cmd'T'. 

This is similar to cmd"S", except that it lets you include a command or z-80 
program for trsdos to execute . 

As long as basic is not overwritten by the execution of the program or 
command, control will return to basic; otherwise, control will return to trsdos. 
(trsdos commands all overlay basic; your z-80 program may not if it loads 
above basic.) 

Example 

CMD"I" ("PROGRAM" 

returns you to trsdos and executes the program file program. 

CMD"!" >M 

returns you to trsdos and executes the command contained in a$. 

CMD" J" 

Calendar Date Conversion 



cmd"J", source, destination 

source is a string expression containing the date to be converted. Its 
contents may be in either of two formats: 

as mm/dd/yy 

bj -yy/ddd 

Format a gives the date in month-day-year sequence. Format b gives 
the day of the year (from 1 to 365 or 366 for leap years), In format b, 
the hyphen Is required. 

destination is a string variable to contain the converted Me. If source Is in 
format a, destination will contain the day of year. If source is in 
format b, destination will contain the elate in format a. 



This command converts dates back and forth between two formats: the standard 
month, day, year, sequence; and a year, day of year, sequence. The content of 
the source string determines which way the conversion goes . 
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Example 

CMD"J" > "11/30/80" > D$ 
Returns the day of the year in d$. 

CMD"J" , "-79/300" , D$ 

Returns the month, day, year, equivalent in D$ (the date for the 300th day 
of 1979). 

Sample Program 

10 CLEAR 50 

20 LINE IN PUT "ENTER FIRST DATE (MM/DD/YY) "5 FD$ 

30 LINE INPUT"ENTER SECOND DATE (MM/DD/YY) "?SD$ 

40 CMD"J" t FD$» Dl$ 

50 CMD"J" > SD$> D2$ 

B0 Yl = MAL(RIGHT$(FD* ,2) ) 

70 Y2 = UAL(RIGHT$(SD$,2) ) 

B0 Jl = VAL(RIGHT$(D1* ,3) ) 

90 J2 = MAL(RIGHT$(D2$>3) ) 

00 SI = Y 1*365 + Jl 

10 S2 = Y2*3G5 + J2 

20 PRINT "THE INTERVAL BETWEEN DATES IS" 5 

30 PRINT ABS(S1-S2)i "DAYS "5 

40 PRINT "(IGNORING LEAP-YEARS)," 

50 INPUT "<ENTER> TO CONTINUE" 5 A$ 

G0 GOTO 20 



CMD"I 9 

Load Z=8(Q) Routine imto RA 



cmd"L", mtiiim 



routine is a string expression containing a file specification for a z-80 
routine or program created by the dump command. If routine is a 
string constant, it must be enclosed in quotes. 



CMD"L" loads a z-80 (machine- language) routine into ram. It would normally 
be used to load a z-so subroutine which is to be accessed directly from basic. 
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The z-80 routine should load into high-RAM and must not overlay the memory 
protect area reserved when you first entered basic (i.e. , the MEMORY SIZE? 
prompt). If you do not overlay basic or trsdos, control will return to basic 
after the program is loaded. 

Example 

The command: 

CMD"L" »"PR0G" 

will load a program file named prog into ram. 

CMD"L" ,P$ 

will load a program which has been specified as p$. 



CMD"0 9 ' 

Sort ("Order' 9 ) am Array 



cm"Q",x,array (start) 

x is an integer variable containing the namiier of items to he sorted. 

amy (start) specifies an array element. The array contains the data to be 
sorted, and start is the suiissript of the first element to he sorted. Tins 
array most be one-dimensional, siring type. The string elements in 
array may be of any length. 



This command sorts (orders) a one-dimensional string array, i.e., a list. You 
may sort all or part of the array, depending on the values you give to x and start. 



Sample Program 



10 CLEAR 10 * 25 + 50 

20 DIM A* (9) 

30 FOR WD = TO 9 

40 PRINT "ENTER NORD «" 5 WD+1 

50 INPUT A*(WD> 

G0 NEXT WD 

70 NZ = 10; CMD"0" > HI, A*(0) 

80 PRINT "HERE IS THE SORTED LIST 

90 FOR WD=0 TO 9 



'ROOM FOR 10 WORDS + EXTRA 
'LIST OF TEN (0-9) 



BttatSiftk 
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100 PRINT A$(WD! 
110 NEXT WD 



CMWV 

Check Pi ' vier Status 



status is a string variable 



cmd'T" makes it possible for Disk basic to check the status of the printer. 

Unlike the video display, the printer is not always available. It may be 
disconnected, offline, out of paper, etc. In such cases, when you try to output 
information to the printer, the Computer will wait until the printer becomes 
available. It will appear to "hang up." To regain keyboard control (and cancel 
the printer operation), press (BREAK) . 

Suppose you have a program which uses printer output. If a printer is not 
available, you don't want the Computer to stop and wait for it to become 
available. Instead, you may want to print a message such as PRINTER 
UNA MAILABLE and go on to some other operation. 

To accomplish this, you need to check the printer status. cmd"P" can be used to 
check the printer's status at any time. It returns the contents as an Ascii-coded 
decimal number. The specific value of this number depends upon the type of 
printer you are using as well as its status at any particular time. The value may 
then be printed or examined by the program. 

Only the four most significant bits are used in this "status byte." In binary, 
these must be: "0011" or else the print operation will not be attempted. To 
check for this "go" condition, and the status byte with 240 and compare the 
result with 48. The meaning of each status bit depends on which printer you 
use. See the printer owner's manual for bit designations. 

Sample Program 

10 CHD"P" ,}{$ 

20 SJ1 = VAL(X$) AND 240 

30 IF STX <> 48 THEN PRINT "PRINTER UNAVAILABLE": STOP 

40 PRINT "PRINTER AVAILABLE" 

50 REM PROGRAM MAY NOW CONTINUE 
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CMD 66 E" 

TUmirn On Clock-Display 



CMD"R" 



This command controls the real-time clock display in the upper-right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Note: The real-time clock is always running (except during cassette or disk i/o), 
regardless of whether the display is on or off. 

Example 

To turn on the clock display type: CMD " R " To turn the display off, type: CMD " T " 

CMD"S" 

Return! to TRSEM ..' 5 



CIWD"S" 



To exit from Disk basic, returning control to trsdos, simply type in the 
command: 

CMD"S" 

To return to basic and recover your program, use BASIC *. However, recovery 
will not always be possible. See basic *. 



The basic prompt lets you know you are in Disk basic. 

READY 
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To exit, type in: 

CMD"S" 

and the trsdos prompt will appear. 

TRSDOS READY 

CMD"T" 

Ikm Off Clock-Display 



CMD"T" 



This command turns off the real-time clock display function. 
However, the clock continues to run. 

Example 

To stop the clock display update type: CMD"T" 
To start the display, type: CMD"R" 

CMD "X" 

Cross-refferai c j off PVogramn Limes 



cmd "X", target 



target is either a basic reserved word (such as primt) or a string-literal. If it 
is a reserved word, it must not be enclosed in quotes; if it is a string- 
literal, it must be enclosed In quotes. 
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This command finds all occurrences of a reserved word or other string literal in 
the resident program. The "finds" are listed on the display as five-digit line 
numbers . 

To search for any basic reserved word (including reserved arithmetic operators), 
use the keyword as-is. To search for anything else (including variable-names and 
text), enclose the text inside quotes. 

For example, suppose you have the following program in memory: 

10 PRINT "THIS IS A TEST" 

20 INPUT "PRESS <ENTER> FOR THE NEXT PRINT MESSAGE" 5 Z$ 

30 A = A + 1 

40 PRINT "+++++++" 

CMD "X" i PRINT will find all occurrences of print, except for cases where 
print was part of a quoted string: lines 10 and 40. 

CMD "X" > "PRINT" will find all occurrences of "print" as a string literal: line 
20. 

CMD ")■!", + will list line 30, but CMD "X" , " + " will list line 40. CMD "X" » 
"A" will list lines 10, 20, and 30. Notice that variables and text are both treated 
as string literals. 

CMD "Z 9? 

Duplicate Output to Video and Printer 



cmd"Z", "switch" 

switch is either ow or off. switch must he enclosed in quotation marks. 
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This command enables or disables dual video/printer output. While the function 
is "on," all video output is copied to the printer, and all printer output is copied 
to the video. (The printer must be on-line when you turn dual output "on.") 

Video and printer output may differ due to intrinsic differences in the printer and 
video devices. 

Examples 

CMD "Z" > "ON" 

Turns dual video/printer output on. 
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CMD"Z"j "OFF" 

Turns dual video/printer output off. 

OFF FN 
Delne Function 



tie r-i n m thai'M '• r r~r<yi, , .) = fan mlh 
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The deffn statement lets you create your own function. That is, you only 
have to call the new function by name, and the associated operations will 
automatically be performed. Once a function has been defined with the deffn 
statement, you can call it simply by inserting fn in front of function name. You 
can use it exactly as you might use one of the built-in functions, like sin, abs, 
and strings. 

The type of variable used for function name determines the type of value the 
function will return. For example, if function name is single precision, then that 
function will return a single-precision value, regardless of the precision of the 
arguments. 

The particular variables you use as arguments in the def fn statement 
(argument- 1, . . .) are not assigned to the function. When you call the function 
later, any variable name of the same type can be used. 

Furthermore, using a variable as an argument in a deffn statement has no effect 
on the value of that variable. So you can use that particular variable in another 
part of your program without worrying about interference from def fn. 

The function can be defined with no arguments at all, if none are required. 
For example: 

DEF FNR = RND (90) + 9 

defines a function to return a random value between 10 and 99. 
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DEF FNR(AtB) = A + INK (B - (A - i>) * RND<0)) 

This statement defines function fnr which returns a random number between 
integers A and B. The values for A and B are passed when the function is 
"called," i.e., used in a statement like: 

Y = FNR(R1 , R2) 

If ri and R2 have been assigned the values 2 and 8, this line would assign a 
random number between 2 and 8 to Y. 

DEF FNL*<X) = STRING$(Xt "-") 

Defines function fnl$ which returns a string of hyphens, x characters long. 
The value for x is passed when the function is called: 

PRINT FNL$(3) 

This line prints a string of 30 hyphens. 

Here's an example showing deffn used for a complex computation — in 
double-precision. 

DEF FNX#(A*> B«) = (A* - B#) * (A# - B») 

Defines function fnx# which returns the double-precision value of the square of 
the difference between a# and b#. The values for a# and b# are passed when 
the function is called: 

S# = FNX#(A#» B#) 

We assume that values for a# and b# were assigned elsewhere in the program. 

Sample Program 

710 DEF FNM(T) = (1087 + S0R(Z73 + T))/1G,52 
720 INPUT "AIR TEMPERATURE IN DEGREES CELSIUS"! T 
730 PRINT "THE SPEED OF SOUND IN AIR OF" T "DEGREES 
CELSIUS IS" FNY(T) "FEET PER SECOND," 



107 



' " "'--I 

V UH TRS-80 MODEL Sii DISK SYSTEM 



DEFUSE 

Define Point of Entry for USR Routine 



defusrw = address 

n equals one of the digits 0, 1,...,S; if n is omitted, is assumed, address 
specifies the entry address to a machine-language routine, address 
must fee in the range [-32768,3275?!. address may be any numeric 
expression or constant from -32718 to 32767. 



defusr lets you define the entry points for up to 10 machine-language routines. 
In non-Disk basic, the addresses were POKEd into ram. This poke method 
cannot be used in Disk basic. 

Examples 

DEFUSR3 = &H7D00 

assigns the entry point X'7D00', 32000 decimal, to the USR3 call. When your 
program calls USR3, control will branch to your subroutine beginning at X'7D00\ 

DEFUSR = (BASE + 1G) 

assigns start address (base + 16) to the usro routine. 

Note: When decimal addresses are given, they are evaluated as signed two-byte 
integers. So, for addresses above 32767, use desired decimal address -65536. 

See usm«. 



INSIR 

Search for Specified String 



instr (position, siring 1, string 2) 

position specifies the position in string 1 where the search is to begin. 
position is optional; if it is not supplied, search automatically begins 
at the first character in string 1. (Position 1 is the first character in 
string 1.) 
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sfr/flg I is the string to lie searched. 

string 2 is the substring you want to search for. 



This function lets you search through a string to see if it contains another string. 
If it does, instr returns the starting position of the substring in the target string; 
otherwise, zero is returned. Note that the entire substring must be contained in 
the search string, or zero is returned. Also, note that instr only finds the first 
occurrence of a substring at the position you specify. 

Examples 

In these examples, a$ = "Lincoln": 

INSTR(A*, "INC") 

returns a value of 2. 

INSTR (A*» "12") 

returns a zero. 

INSTR (A*. "LINCOLNABRAHAM") 

returns a zero. For a slightly different use of instr, look at 

INSTR (3. "1232123" , "12") 

which returns 5 . 



This program gets search and target text from the keyboard, then locates all 
occurrences of the target text in the search text. Line 90 is just for "show." 



10 CLEAR 1000 

20 CLS 

30 INPUT 

40 INPUT 

45 CLS 

50 C = 



SEARCH TEXT" i S$ 
TARGET TEXT"! T$ 



COUNT 



: P = 1 'P = POSITION* C 
60 F = INSTR(P»S$»T$) 
70 IF F = THEN 120 
80 C = C + 1 
90 PRINT i0,LEFT$(S$»F-l) + STRINGS ( LEN( T$ ) , 191 ) + 

■ RIGHT* (S*»LEN(S$)-F-LEN(T$)+1) 
100 P = F + LEN(T$) 

110 IF P <= LEN(S$) - LEN(T*) + 1 THEN G0 
120 PRINT "FOUND "i Ci "OCCURRENCES" 



—HI 
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LINE INPUT 

Jfaiput a Line from Keyboard 



line input "prompt" ;variable 

prompt is a prompting message. 

variable is the name that will be assigned to the fine you type in. 



line input (or lineinput — the space is optional) is similar to input, except: 

The Computer will not display a question mark when waiting for your 
operator's input. 

• Each line input statement can assign a value to just one variable. 

• Commas and quotes your operator can use as part of the string input. 

• Leading blanks are not ignored — they become part of variable. 
The only way to terminate the string input is to press ( ENTER) . 

line input is a convenient way to input string data without having to worry 
about accidental entry of delimiters (commas, quotation marks, colons, etc.). 
The (EHTER) key serves as the only delimiter. If you want anyone to be able to 
input information into your program without special instructions, use the line 
input statement. 

Some situations require that you input commas, quotes and leading blanks as 
part of the data, line input serves well in such cases. 

Examples 

LINE INPUT A* 

Input a$ without displaying any prompt. 

LINE INPUT "LAST NAME) FIRST NAME? " 5N$ 

Displays a prompt message and inputs data. Commas will not terminate the 
input string, as they would in an input statement. 

Sample Program 

200 REM CUSTOMER SURVEY 
205 CLEAR 1000 
207 PRINT 
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210 LINE INPUT "TYPE IN YOUR NAME "5 A* 

220 LINE INPUT "DO YOU LIKE YOUR COMPUTER? "5 B$ 

230 LINE INPUT "WHY? " 5 C$ 

235 PRINT 

240 PRINT A$ i PRINT 

250 IF B$ = "NO" THEN 270 

260 PRINT "I LIKE MY COMPUTER BECAUSE "5 C$ ;END 

270 PRINT "I DO NOT LIKE MY COMPUTER BECAUSE "5 C$ 

Notice that when line 210 is executed, a question mark is not displayed after the 
statement, "Type in your name." Also, notice on line 230 you can answer the 
question "Why" with a statement full of delimiters, commas and quotes. 



Eeplace Portion of String 



mids (iUsiring, position, length) = replacement-string 

oldstring is the variable-name of the string you want to change. 

position is tine ojimiSiic expression specifying the position of the first 
character to be changed. 

length is a numeric expression specifying the number of characters to be 
replaced. 

replacement-string is a string expression to replace the specified portion 
of oldstring. 

Note: If replacement-string is shorter than length-, then the entire repiacement- 
string will tie used. 



This statement lets you replace any part of a string with a specified new string, 
giving you a powerful string editing capability. 

Note that the length of the resultant string is always the same as the original 
string. 

Examples 

a$ = "Lincoln" in the examples below: 
MID$(A$» 3, 4) = "12345":! PRINT A$ 
which returns LH234N. 
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MID$(A$» 1 t Z) = "": PRINT A$ 

which returns Lincoln. 

MID$(A*» 5) = "12345": PRINT A$ 

returns lino 23. 

MID$(A$, 5) = "01"; PRINT A$ 

returns lincoin. 

HID$(A$» 1 > 3) = "*##": PRINT A$ 

returns ***coln. 



Sample Program 



770 CLS: PRINT: PRINT 

7B0 LINE INPUT "TYPE IN A MONTH AND DAY MM/DD, "5 5$ 

790 P = INSTR(S$, "/") 

800 IF P = THEN 780 

B10 MID*(S*» Pt 1) = CHR*(45) 

820 PRINT S$ " IS EASIER TO READ. ISN'T IT?" 

This program uses instr to search for the slash ("/"). When it finds it 
(if it finds it), it uses mid$ = to substitute a " — " (CHR$(45)) for it. 



NAME 

Eem ? i n 1 > b 1 fti e C 'vjrireiiit Program 



name newline, startline, increment 

newiine specifies the new line number of the first line to be renumbered. 

If omitted, 10 is used. 

startline specifies the line number in the original program where 
renumbering will start. If omitted, the entire program will be 
renumbered. 

increment specifies the increment to be used between each successive line 
number. If omitted, 10 is used. 
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Examples 

NAME 

Renumbers the entire program: 10, 20, 30, . . . 

NAHE 6000,5000 »100 

Renumbers all lines numbered from 5000 up; the first renumbered line will 
become 6000, and the following lines will be incremented by 100. All line 
references within your program will be renumbered also. 

USRm 

Call to User's Exi ernal ^r broi tin 2 



usr/j (nmexp) 



where n specifies one oS ten available usr calls, 0=0,1,2,. ..,9. If-ffis 
omitted, zero is assumed. 

nriiexp is an integer from -327S8 to 32757 and is passed as an integer 
argument to the routine. 



These functions (usro through USR9) transfer control to machine-language 
routines previously defined with defusrjj statements. 

When a urs call is encountered in a statement, control goes to the address 
specified in the defusrtj statement. This address specifies the entry point to your 
machine-language routine. 

Note: If you call a usrh routine before defining the routine entry point with 
DEFUSRn, an illegal function call error will occur. 

You can pass one argument and retrieve one output value directly via the usr 
argument; or you can pass and retrieve arguments indirectly via poke and peek 
statements. 



Example 

1.0 DEFUSR1=&H7D00 

20 REM,, .MORE PROGRAM LINES HERE 

100 A=USR1(X) 

The effect of this sequence is to: 
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1 . Define usr as a routine with an entry point at hex 7D00 (line 10). 

2. Transfer control to the routine; the value x can be passed to the routine if the 
routine makes the call described below (line 100). 

3. When the routine returns to basic, the variable A may contain the value 
passed back from the routine (if your routine makes the jump described 
below); otherwise A will be assigned the value of x (line 100). 

Passing arguments to and from USR routines 

There are several ways to pass arguments back and forth between your basic 
main program and your usr routines: the two major ways are listed below. 

1. poke the argument(s) into fixed ram locations. The machine-language routine 
can then access these values and place results in other ram locations. When 
the routine returns control to basic, your program can peek into these 
addresses to pick up the "output" values. This Is the only way to pass two 
or more arguments back and forth. 

2. Pass one argument to the routine as the argument in the usRn call, then use 
special rom calls to access this argument and return a value to basic. This 
method is limited to sending one argument and returning one value (both 
are integers). 

rom Calls 

call 0A7FH Puts the usr argument into the hl register pair; H contains msb, l 
contains lsb. This call should be the first instruction in your usr 

routine. 

jp 0A9AH Use this jump to return to basic; the integer in hl becomes the 
output of the usr call. If you don't care about returning hl, then 
execute a simple RETurn instruction instead of this jump. 

Listed below is an assembled program to white out the display (an "inverse" 
clear key!). Don't type it in. Type in the basic program that follows it. 



7D00 



3C00 
00BF 
03FF 



00100 


i 








00110 


; zap 


OUT 


SCREEN 


USR FUt 


00120 


5 








00130 






ORG 


7D00H 


00140 


5 








00150 


i EQUATES 






001G0 


! 








00170 


VIDEO 




E0U 


3C00H 


00180 


WHITE 




E0U 


0BFH 


00190 


COUNT 




EOU 


3FFH 


00200 


9 









5 START OF VIDEO RAH 
iALL WHITE GRAPHICS BYTE 
? NUMBER OF BYTES TO MOVE 



110 ! PROGRAM CHAIN MOVES X'BF' INTO ALL OF VIDEO RAM 



00220 
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7D00 


21003C 


00230 ZAP 


LD 


HL.UIDEO 


i SOURCE ADDRESS 


7D03 


3BBF 


00240 


LD 


(HL> .WHITE 


iPUT OUT 1ST BYTE 


7D05 


11013C 


00250 


LD 


DE.VIDEO+1 


.DESTINATION ADDRESS 


7D0B 


01FF03 


002B0 


LD 


BC, COUNT 


.NUMBER OF ITERATIONS 


7D0B 


EDB0 


00270 
00280 . 


LDIR 




.DO IT TO IT! ! ! 


7D0D 


C9 


00290 


RET 




5 RETURN TO BASIC 


7D00 




00300 


END 


ZAP 





This routine can be POKEd into ram and accessed as a usr routine. First start basic and answer the 
MEMORY SIZE question with 31993. Then run the program. 

100 ' PROGRAM: USR1 

110 ' EXAMPLE OF A USER MACHINE LANGUAGE FUNCTION 

115 ' DEPRESS THE '1' KEY WHILE NUMBERS ARE PRINTING TO STOP 

120 ' 

130 ' ******* POKE MACHINE PROGRAM INTO MEMORY ******* 

140 ' 

150 DEFUSR1 = &H7D00 

160 FOR X = 32000 TO 32013 '7D00 HEX EQUAL 32000 DECIMAL 

170 READ A 

180 POKE X» A 

190 NEXT X 

192 ' 

194 ' ******* CLEAR SCREEN & PRINT NUMBERS 1 THRU 100 ******* 

19G ' 

200 CLS 

205 PRINT TAB (15)? "WHITE-OUT USER ROUTINE": PRINT 

2i0 FOR X = 1 TO 100 

220 PRINT X! 

225 A$ = INKEY*: IF A$ - "@" THEN END 

230 NEXT X 

240 ' 

250 ' ******* JUMP TO WHITE-OUT SUBROUTINE ******* 

260 ' 

270 X = USR1 (0) 

280 FOR X = 1 TO 1000: NEXT X 'DELAY LOOP 

290 GOTO 200 

300 ' 

310 ' ******* DATA IS DECIMAL CODE FOR HEX PROGRAM ******* 

320 ' 

330 DATA 33.0.60,54.191 .17.1 .60.1 .255. 3,237.176,201 

Run the program. An equivalent basic white out routine takes a long time by comparison! 



115 




Disk-Related Features 

Disk basic provides a powerful set of commands, statements and functions 
relating to disk i/o under trsdos. These fall into two categories: 

1. File manipulation: dealing with files as units, rather than with the distinct 
records the files contain. 

2. File access: preparing data files for i/o; reading and writing to the files. 

Under the heading, File Manipulation, we will discuss the following 
commands. 



Delete a program or data file from the disk 

Load a basic program from disk 

Merge an Ascii-format basic program on disk with one 
currently in ram 

Load and execute a basic program stored on disk 

Save the resident basic program on disk 

Under the heading, File Access, we will discuss the following statements and 
functions. 



kill 
load 

MERGE 

run "program" 
save 



Statements 

OPEN 

CLOSE 

INPUT # 

LINE INPUT# 

PRINT# 

HELD 

GET 

PUT 

LSET 

RSET 

Functions 

CVD 

CVI 
CVS 

EOF 
LOC 



Open a file for access (create the file if necessary) 

Close access to the file 

Read from disk, sequential mode 

Read a line of data, sequential mode 

Write to disk, sequential mode 

Assign field sizes and names to random-access file buffer 

Read from disk, random access mode 

Write to disk, random access mode 

Place value in specified buffer field, add blanks on the 
right to fill field 

Place value in specified buffer field, add blanks on the left 
to fill field 

Restore double-precision number to numeric form after 
GETting from disk 

Restore integer to numeric form after GETting from disk 

Restore single-precision number to numeric form after 
GETting from disk 

Check to see if end of file encountered during read 

get current record number. 
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lof Return number of last record in file 

mkd$ Convert double -precision number to string so it can be put 

on disk 

mki$ Convert integer to string so it can be put on disk 

mks$ Convert single-precision number to string so it can be put 

on disk 



117 



JS TBS-80 MODEL 111 DBSK SYST EM 



Fie Manipulation 

KILL 

Delete a Fie from the Disk 



kill exp$ 

exp$ defines a file specification far an existing file. 



This command works like the trsdos kill command — see trsdos Library 
Commands. 

Example 

KILL"0LDFILE/BAS.PSW1" 

deletes the file specified from the first drive which contains it. 

Do not kill an open file, or you may destroy the contents of the diskette. (First, 
close the open file.) 

LOAD 

Load BASIC Program File from Disk 



torn exfl${fil 

where exp$ defines a filsspec for a basic program file stored on disk. 
r \h^: b,„' *s b bs i*. the program afti i i! is loaded. 



This command loads a basic program file into ram; if the r option is used, 
basic will proceed to run the program automatically; otherwise, basic will 
return to the command mode. 
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load without the r option clears all variables and closes all open files, load 
with the r option clears all variables but does not close the open files. 

load with the r option is equivalent to the command run exp$,K. Either of 
these commands can be used inside programs to allow program chaining — one 
program calling another, etc. 

Example 

L0AD"PR0G1/BAS:2" 

Clears resident basic program and loads progi/bas from Drive 2; returns to 
basic command mode. 



am wltt Resideii r Proi 



MERGE eXBS 



exp $ is fiif'- specification for a 
sawed witi the a option. 



\u,i''if MJi « r I I if, e.g., ^rograu 



merge is similar to load — except that the resident program is not erased before 
the new program exp$ is loaded. Instead, the new program is merged into the 
resident program. 

That is, program lines in exp$ will simply be inserted into the resident program 
in sequential order. If line numbers in exp$ coincide with line numbers in the 
resident program, the resident lines will be replaced by those from exp$. 
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Program on Disk 


Program in Ram 


Merged Program in R 






10 


+ 




10 






10 








20 


20 






30 


30 






40 


40 






50 


50 






60 


60 






70 


70 






90 


90 j 


90 






100 




100 






110 




110 






120 




120 





Sample Use 

Save this program in ascii format. 

1000 REM . , , SUBROUTINE TO BAY HELLO 
1010 PRINT "HELLO!" 
1020 RETURN 



Type NEW (ENTER) , then type in this program. 

100 CLB 

110 PRINT "LET'S CALL THE SUBROUTINE . ♦ ," 

120 PRINT "DIALING NOW , , ," 

,130 FOR 1 = 1 TO 1000 ; NEXT 

140 GOSUB 1000 

150 PRINT "BACK FROM SUBROUTINE." 

160 END 

Now type MERGE "file" using the file name given to the first file. List the program. Then run it. 



[6 £ 1 
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Load and Execute a Program from Disk 



run ft7e[.Rl 



file is the name *tJ a basic program file. II ,$ n dnng expression. (If a string 
constant is used, it must be enclosed m quotes.) The ,r option causes 
basic to leave open files open. If omitted, open files are closed before 

the program Is run. 



120 



This command loads and executes a basic program stored on disk. It may be 
used inside a program to allow chaining (one program calling another). 

Examples 

RUN "PROG" 

Loads and executes prog (all open files are closed first). 

A$="NEWPRGG" 

RUN A$ > R 

Loads and executes newprog (all open files remain open). 




iave rrogn 



save file [,a] 



tile is the name of a basic program file. If is a string expression. 
(If a string constant 1? ised, ii must be sncBosed in quotes ) 

a cause:, the file to be stored In asm ra ffier than compresses! format. 



This command lets you save your basic programs on disk. You can save the 
program in compressed or ascii format. 

Using compressed format takes up less disk space and is faster during both 

saves and loads. Using the ASCII option makes it possible to do certain things 

that cannot be done with compressed format basic files. \A 



For example: 

8 The merge command requires that the disk file be in ascii form. 



r 



V / 



vr 



( \ 



Programs which read in other programs as data will typically require that the / x Jp 

data programs be stored in ascii. 

• The trsdos command append also requires that disk files be in asch form. 
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Examples 

SAUE"FILE1/BAS. J0HN0D0E:3" 

saves the resident basic program in compressed format with the file name filei , 
extension /bas, password johnqdoe; the file is placed on Drive :3. 

SAVE"MATHPAK/T>!T" .A 

saves the resident program in ascii form, using the name mathpak/txt, on the 
first nonwrite-protected diskette. 

Upon completion of a save, basic returns in the command mode. 
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This section is divided into four parts: 

1 . Creating files and assigning buffers — open and close 

2. Statements and functions 

3. Sequential i/o techniques 

4. Random i/o techniques 

If this is your first experience with disk file access, you should concentrate on 
parts 1 , 3 and 4, perhaps just skimming through part 2 to get a general idea of 
how the functions and statements work. Later you can go back to part 2 and 
learn the details of statement and function syntax. 

Creating Fies and Assigning Buffers 

During the initialization dialog, you type in a number in response to how many 
files? The number you type in tells basic how many buffers to create to handle 
your disk accesses (reads and writes). 

Each buffer is given a number from 1 to 15. If you type: 



HOW MANY FILES? 3V (MM) 

basic sets aside 3 buffers, numbered 1,2,3. 

You can think of a buffer as a waiting area that data must pass through on the 
way to and from the disk file. When you want to access a particular file, you 
must tell basic which buffer to use in accessing that file. You must also tell 
basic what kind of access you want — sequential output, sequential input, or 
random input/output. 

All this is done with the open statement, and "undone" with the close 
statement. 



OPEN 
Dpd bi a Fie 



qpem made, buffer, file record lengih 

modie is a its ii ig i icpression contain! i * one of the toitowii g: 

i Sepi itia impmi sta rii ii i a! the first i ee§ rd If She lite is in i' hi * i f > 

ii will be sm&M'L 



mmm 
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o Sequential oytput starting at the first record. IS the file is not 
found, it will -be created. 

e (Extend) Sequential output starting at end of file, if the file is not 
found, it will be created. 

'■ the i file is not found, it will be created. 



r Randominpui/output, 
IS modeM a consta it, ?! must be enclosed in poles, coois be a vab-iabcc / 

buffer is a numeric expression specifying which buffer is to be used. 

file is a string expression containing the file specification. If a constant is as a<5o vC P 
used, it must be enclosed in quotes. 

n smi-lengii is & numeric expression from to 2§§ specifying the logical 
record length. II : >5 the same as 256. This option may only be used if 
rariable-lengfh records were requested during initialization (How 
Many Files?). If record-length is omitted, 256 is used, record-length 
is used with Random access only. 



This statement lets you create a file, write data into it, update it, and read it. For 
details on file access, see Methods of Access later in this section. 



If file includes a drive specification/ basic will use only the specified drive. If 
no drive is specified, basic will search for a matching file, starting with the 
master drive (usually Drive 0). 



Examples 

OPEN "0" i 1 > 



"DATAFILE" 



Opens datafile (creates it if it doesn't already exist) for sequential output. 
Output will be done through buffer #1 . Records will be 256 bytes long. Since 
the "o" mode is specified, output will start at the first record in the file. 
If "e" is used instead of "o", output will start at the end of the file. 



OPEN 



'PAYROLL/A:!" » G4 



Opens/creates payroll/a for random input/output. Access will be through 
buffer #2. Records will be 64 bytes long (if basic was initialized for variable- 
length records). 



&€lo\\X> i.e.k)QTO 



BUFFER = 3: FILE* = "DATA" 
OPEN "R"» BUFFER. FILE$» RECL 



RECLN = 128 



Li 



stcxoe. 



Opens/creates data for random input/output. Access will be through buffer #3. 
Records will be 128 bytes long ( if basic was initialized for variable-length 
records). 
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Close Access to the Fie 



close [nmexp [, nmexp. , .] ] 

/i.T/exp has a value from 1 to 15, and refers to the file's buffer number 

(assigned when the file was opened). If nmexp I s unified, all §p@i 
files will be closed. 



This command terminates access to a file through the specified buffer(s). 
If nmexp has not been assigned in a previous open statement, then 

close nmexp 

has no effect. 

Examples 

CLOSE 1 ,2,8 

Terminates the file assignments to buffers 1, 2 and 8. These buffers can now be 
assigned to other files with open statements. 

CLOSE FIRST'Z + COUNT/f. 

Terminates the file assignment to the buffer specified by the sum 
(first% + COUNT%). 

Do not remove a diskette which contains a file opened for writing (mode — O, 
E, or R). First close the file. This is because the last 256 bytes of data may not 
have been written to disk yet. Closing the file will write the data, if it hasn't 
already been written. 

Any modification to the resident program (new, editing, load, merge, etc.) 
will cause open files to be closed. 
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INPUT# 

Seep e tial ] 2 >ii from Disk 



ihput# nmexp, !/ar[,rar. J 

where /fme^p specifies a sequential input file buffer, nmeifi=t,2,. ,,11. 
sot is the variable name to contain the data ffroj-* the file. 



This statement inputs data from a disk file. The data is input sequentially. That 
is, when the file is first opened, a pointer is set to the beginning of the file. 
Each time data is input, the pointer advances. To start over reading from the 

beginning of the file, you must close the file and re-open it. 

input# doesn't care how the data was placed on the disk — whether a single 
print# statement put it there, or whether it required 10 different print# 
statements. What matters to input# are the positions of the terminating 

characters and the eof marker. 

To input# data successfully from disk, you need to know ahead of time what 
the format of the data is. Here is a description of how input# interprets the 
various characters it encounters when reading data. 

When inputting data into a variable, basic ignores leading blanks; when the 
first non-blank character is encountered, basic assumes it has encountered the 
beginning of the data item. 

The data item ends when a terminating character is encountered or when a 
terminating condition occurs. The particular terminating characters vary, 
depending on whether basic is inputting to a numeric or string variable. 

Special Note 

Here's an important exception to keep in mind in reading the following material. 



When OTTER) (a carriage return) is preceded by & (a line feed), the OTTER) is 
not taken as a terminator. Instead, it becomes a part of the data item (string 
variable) or is simply ignored (numeric variable). 

(To enter the © character from the keyboard, press the down-arrow character. 
To enter the OTTER) character, press OTTER) .) 



This exception applies to all cases noted below where OTTER) is said to be a 
terminator. 
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Suppose the data image on disk is 



1.234 -33 27 (ElTEfD 



[ENTER) denotes a carriage-return character (ascii code decimal 13). 

Then the statement 

INPUT«i , A,B»C 

or the sequence of statements 

INPUT#i .A: INPUT*! »B: INPUT#1 ,C 

will assign the values as follows: 

A =1.234 
B=-33 

C = 27 

This works because blanks and (EMTER) serve as terminators for input to numeric 
variables. The blank before 1.234 is a "leading blank," therefore it is ignored. 
The blank after 1.234 is a terminator; therefore basic starts inputting the second 
variable at the - character, inputs the number -33, and takes the next two 
blanks as terminators. The third input begins at the 2 and ends with the 7. 

String Input 

When reading data into a string variable, input ignores all leading blanks; 
the first non-blank character is taken as the beginning of the data item. 

If this first character is a double-quote ("), then input will evaluate the data as 
a quoted string: it will read in all subsequent characters up to the next double- 
quote. Commas, blanks, and (ENTER ) characters will be included in the string. 
The quotes themselves do not become a part of the string. 

If the first character of the string item is not a double-quote, then input will 
evaluate the data as an unquoted string: it will read in all subsequent characters 
up to the first comma, or (ENTER) . If double-quotes are encountered, they will be 
included in the string. 

For example, if the data on disk is: 

PECOS, TEXAS "GOOD MELONS" 

Then the statement 

INPUT*! i A$ ,B$ ,C$ 
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would assign values as follows: 

A$ = PECOS 

B$= TEXAS "GOOD MELONS" 

C$ = null string 

If a comma is inserted in the data image before the first double quote, c$ will 
get the value, good melons. 

These are very simple examples just to give you an idea of how input works. 
However, there are many other ways to input data — different terminators, 
different target variable types, etc. 

Rather than taking a shotgun approach and trying to cover them all, we'll give a 
generalized description of how input works and what the terminating characters 
and conditions are, and then provide several examples. 

When basic encounters a terminating character, it scans ahead to see how many 
more terminating characters it can include with the first terminator. This ensures 
that basic will begin looking for the next data item at the correct place. 

The list below defines the various terminating sets input# will look for. It will 
always try to take-in the largest set possible. 

Numeric-input terminator sets 

end of file encountered 

255th data character encountered 

, (comma) 

(Ml 
(ESTER) © 

[ . . .] [ (ENTER) ] 

[ . . .] [ (ENTER) © 1 

Quoted-string terminator sets 
end of file encountered 
255th data character encountered 
" (double quote) 

"[ •••][,] 

" [ . . .][ (ENTER)! 

" [ . . .nun©©] 

Unquoted-string terminator sets 

end of file encountered 

255 th data character encountered 

' (ENTER) r©1 

Figure 13 describes how input# assigns data to a variable. 
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EXAMINE NEXT 
CHARACTER 



4T 



IGNORE IT £ 




PICKUP THE 

TERMINATOR 

SET 






4L 



GET DATA FROM 
TEMPORARY 
SAVE AREA 



_y 



PUT IT INTO 
TEMPORARY 
SAVE AREA 



EVALUATE IT 



EXAMINE NEXT 
CHARACTER 



ASSIGN TO 
""?" VARIABLE 




Figure 13. Input process. 



The following table shows how various data images will be read-in by the 
statement: 

INPUTsl »A,B»C 



Ek.# 



Image on disk 



123.45 [EWTEffi ^l 8.2E4 7000 (EWTlER) 



3©dHH) 4 HWTER1 5 (ENTER) AlZeof 



t ».2,3»4 (INTER) 



l >3 » eof 



Values 
assignee! 



A= 123.45 
B = 82000 
C = 7000 



A = 34 
B = 5 
C = 



A=1 
B = 
C = 2 



A=1 
B = 3 
C = eof error 



(eof = end of file): 

In Example 2 above, why does variable c get the value 0? When the input 
reaches the end of file, it terminates that last data item, which then contains 
"A12." This is evaluated by a routine just like the basic val function — which 
returns a zero since the first character of "A12" is a non-numeric. 



t.^iV'V.;'^ 
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USE SYSTEM 



In Example 3, when input# goes looking for the second data item, it 

immediately encounters a terminator (the comma); therefore, variable B is given 

the value zero. 

The following table shows how various data images on disk will be read by the 

statement: 

INPUT#1 »A$.B$ 



Imag e on disk 



'ROBERTS . J . "ROBERTS »M , N eof 



ROBERTS. J. t ROBERTS. M.N. (ENTER) 



THE WORD "QUO" .12345,789 (MM 



BYTE© (ENTER) UNIT OF MEMORY eof 



Values assigned 



A$:ROBERTS,J. 
B$:ROBERTS,M.N. 



A$:ROBERTS 
B$:J. 



A$:THE WORD "QUO ,: 

B$: 12345. 789 



A$:BYTE©(HTiB) 
UNIT OF MEMORY 
B$:nu)l (eof error) 



In Example 3, the first data item is an unquoted string, therefore, the double- 
quotes are not terminators, and become part of AS. 

In Example 4, the (EiTER) is preceded by an &, therefore it does not terminate 
the first string; both & and fEMTER ) are included in a$. 

LINE INPUT# 

Read a Line of Text from Disk 



line mpin#nmes[fi,vat$ 

where nmexp specifies a sequential output file buffer, nmexp =1,2,... ,15. 
var$ is the variable name to contain the string data. 



Similar to line input from keyboard, this statement reads a "line" of string 
data into var$. This is useful when you want to read an Ascn-format basic 
program file as data, or when you want to read in data without following the 
usual restrictions regarding leading characters and terminators. 
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line input (or lineinput — the space is optional) reads everything from the first 
character up to: 

1 . an (ENTER) character which is not preceded by & 

2. the end of file 

3. the 255th data character (this 255 character is included in the string) 

Other characters encountered — quotes, commas, leading blanks, © ( ENTER) 
pairs — are included in the string. 

For example, if the data looks like: 

10 CLEAR 500 (ENTER) 

20 OPEN" I" »1 *"PR0G" (EJUS) 



then the statement 
LINEINPUTttl ,A$ 
could be used repetitively to read each program line, one line at a time. 






PEINT# 

5s fltin ^ i i Wn its i d Di k Fife 



mm#nmexp, [using formats;] exp[p exp. . .] 

where nmexp specifies a sequential output file buffer, nmexp= 1,2, ...,15. 

formats is a sequence of field specifiers used with the using option. 

F is a delimiter placed ijetween every two expressions to be PRimed to disk; 
either a semi-colon or comma can be used (semi-colon is preferable). 

exp is the expression to he evaluated and written to disk. 



This statement writes data sequentially to the specified file. When you first open 
a file for sequential output, a pointer is set to the beginning of the file, therefore 
your first print# places data at the beginning of the file. At the end of each 
print# operation, the pointer advances, so the values are written in sequence. 



mm m 
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A print# statement creates a disk image similar to what a print to display 
creates on the screen. Remember this, and you'll be able to set up your print# 
list correctly for access by one or more input statements. 

print# does not compress the data before writing it to disk; it writes an ascii- 
coded image of the data. 

For example, if A = 123.45 

PRINT#1 »A 

will write a nine-byte character sequence onto disk: 

123.45 (ENTER) 

The punctuation in the print list is very important. Unquoted commas and semi- 
colons have the same effect as they do in regular print to display statements. 

For example, if A = 2300 and b = 1.303, then 

PRINT#1 »A»B 

places the data on disk as 



2300 1,303 (HUB) 

The comma between A and b in the print# list causes 10 extra spaces in the 
disk file. Generally you wouldn't want to use up disk space this way, so you 
should use semi-colons instead of commas. 

PRINT*! »A!B 

writes the data as: 



2300 1.303 (ENTER) 

print# with numeric data is quite straightforward — just remember to separate 
the items with semi-colons. 

print# with string data requires more care, primarily because you have to insert 
delimiters so the data can be read back correctly. In particular, you must 
separate string items with explicit delimiters if you want to input# them as 
distinct strings. 

For example, suppose: 

A*="J0HN 0. DOE" andB*="100-01-001" 

Then: 

PRINTbI > A*»B* 

would produce this image on disk: 



JOHN 0. DOE100-01-001 (ENTER) 

which could not be input back into two variables. 

The statement: 
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PRINTttl . A$5" »"5B* 

would produce: 

JOHN 0, DOE. 100-01-001 

which could be input# back into two variables. 

This method is adequate if the string data contains no delimiters — commas or 
(ENTER) — characters. But if the data does contain delimiters or leading blanks 
that you don't want to ignore, then you must supply explicit quotes to be written 
along with the data. For example, suppose A$ = "DOE . JOHN 0." and B$ = " 100 
-01-001" 

If you use 

PRINT* 1 .A$i" »"SB$ 
the disk image will be: 



DOE. JOHN 0, .100-01-001 (ENTER) 

When you try to input this with a statement like 

INPUT#2.A$.B$ 

A$ will get the value doe, and b$ will get john q. — because of the comma after 
doe in the disk image. 

To write this data so that it can be input correctly, you must use the chrs 
function to insert explicit double quotes into the disk image. Since 34 is the 
decimal ascii code for double quotes, use chr$(34) as follows: 

PRINT*1 »CHR$(34) iA$!CHR$(34) !B$ 

this produces the disk image 



"DOE. JOHN Q, "100-01-001 CENTER) 
which can be read with a simple 

INPUT«2.A$B$ 

Note: You can also use the chrs function to insert other delimiters and control 
codes into the file, for example: 

CHRS(iO) © Line Feed 

chr$(13) carriage return ((ENTJR)character) 

chr$( n ) or chr$( 1 2) line-printer top-of-f orm 

USING Option 

This option makes it easy to write files in a carefully controlled format. 
For example, suppose: 

A$="LUDWIG" 
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B*="VAN" 
C$="BEETHOMEN" 

Then the statement 

PRINT«i tUSING"! , !, 1 Z" 5A*5B*5Ct 

would write the data in nickname form: 

L.U.BEET < ENTER) 

(In this case, we didn't want to add any explicit delimiters.) See the print using 
description in the level h basic Reference Manual for a complete explanation of 
the field-specifiers. 

Random Access Statements 

FIELD 

Organize a Random File-Buffer into Fields 



field nmexp,nmexp1 Asvart$[,nmexp2 as var2$. . .] 

nmsxp specifies a random access fife buffer, w/nejr/?=1,2,...,15. 

nmsKfi speslfiss the length of the first field. 

var1$ defines a variable name for the first field. 

mr,exB2 specifies the length of the second field. 

var2$ defines a variable name for the second field. 

. . . Subsequent nmexpks, var$ pairs define other fields in the buffer. 

Mote: The sum of all the field-Iangths must not exceed the record length, and 
should equal the record length. 



Before FiELDing a buffer, you must use an open statement to assign that buffer 
to a particular disk file (you must use random access mode). Then use the field 
statement to organize a random file buffer so that you can pass data from basic 
to disk storage and vice-versa. 

Each random file buffer has up to 256 bytes which can store data for transfer 
from disk storage to basic or from basic to disk. (When variable-length files are 
used, maximum may be from 1 to 256.) However, you need a way to access this 
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buffer from basic so that you can either read the data it contains or place new 
data in it. The field statement provides the means of access. 

You may use the held statement any number of times to "re-organize" a file 
buffer. FiELDing a buffer does not clear the contents of the buffer; only the 
means of accessing the buffer (the field names) are changed. Furthermore, two 
or more field names can reference the same area of the buffer. 

Examples 

FIELD 1 > 128 AS A$ , 123 AS B$ 

This statement tells basic to assign the first 128 bytes of the buffer to the string 
variable a$ and the remaining 128 bytes to b$. If you now print a$ and b$, you 
will see the contents of the buffer. Of course, this value would be meaningless 
unless you have used get to read a 256-byte record from disk. 

Note: All data — both strings and numbers — must be placed into the buffer in 
string form. There are three pairs of functions (mki$/cvi,mks$/cvs,mkd$/cvd) 
for converting numbers to strings and vice- versa. See "Functions" below. 

FIELD 3. IB AS NH$ , 25 AS AD$ » 10 AS CY$ , 2 AS ST$ H AS ZP$ 

The first 16 bytes of buffer 3 are assigned the buffer name nm$; the next 25, 
ads; the next 10, cy$; the next 2, st$ and the next 7, zp$. The remaining 196 
bytes of the buffer are not fielded at all. 

More on field names 

Field names, like nms,ad$,cy$,st$, and zp$, are not string variables in the 
ordinary sense. They do not consume the string space available to basic. 

Instead, they point to the buffer field which you assigned with the field 
statement. That's why you can use: 

100 FIELD 1 >255 AS A$ 

without worrying about whether 255 bytes of string space are available for a$. 

If you use a buffer field name on the left side of an ordinary assignment 
statement, that name will no longer point to the buffer field; therefore, you 
won't be able to access that field using the previous field name. 

For example, 

A$ = B$ 

nullifies the effect of the field statement above (line 100). 

During random input, the get statement places data into the 255-byte buffer, 
where it can be accessed using the field names assigned to that buffer. During 
random output, lset and rset place data into the buffer, so you can then put 
the buffer contents into a disk file. 
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Often you'll want to use a dummy variable in a held statement to "pass 
over" a portion of the buffer and start fielding it somewhere in the middle. 
For example: 

FIELD It 16 AS CLIENT$(1). 112 AS HIST$(1) 

FIELD 1» 128 AS DUMMY$ > 1G AS CLIENT$(2)j 112 AS HIST$(2) 

In the second held statement, dummys serves to move the starting position of 
client$(2) to position 129. In this manner, two identical "subrecords" are 
defined on buffer number 1 . We won't actually use dummy$ to place data into 
the buffer or retrieve it from the buffer. 

The buffer now looks like this: 



16 


112 


16 


112 



CL$ 
(D 



HIST$ 
(1) 



CL$ 

(2) 



HISTS 
(2) 



>UMMY$ 



Read a Record from Disk— Random Access 



get nmexp1[,ttmexp2\ 

ttmespl specifies \ random access >ib buffer, nmexi 1 = 1,2, ...,15. 

aim xfk &c «. ; : pr v&im tecsn h &b i>i \k fi! 5 if s h tied this 1 1 -i^l 
reeord will be read. 



This statement gets a data record from a disk file and places it in the specified 
buffer. Before GETting data from a file, you must open the file and assign a 
buffer to it. That is, a statement like: 

open "R" ,nmexpl ,filespec 

is required before the statement: 

get nmexpl ,nmexp2 

get tells basic to read record nmexpl from the file and place it into the nmexpl 
buffer. If you omit the record number in get, basic will read the current record. 
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The "current record" is the record whose number is one higher than that of the 
last record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 

For example: 

Program statement Effect 

1000 OPEN"R",l,"NAME/BAS" 

1010 FIELD 1,... 

1020 GET 1 

1025 REM... ACCESS BUFFER 
1030 GET 1 ,30 

1035 REM... ACCESS BUFFER 
1040 GET 1,25 

1046 REM... ACCESS BUFFER 
1050 GET 1 



Open name/bas for random access 
using buffer 1 

Structure buffer 

get record 1 into buffer 1 

get record 30 into buffer 1 

get record 25 into buffer 1 

get record 26 into buffer 1 



If you are using variable-length records (not fixed-length), an attempt to get 
past the end of file will produce an error. 

If you are using fixed-length records, the same attempt will return a null record 
and no error will occur. To prevent this from occurring, you can use the lof 
function to determine the number of the highest numbered record. 



Write a Record to Disk— Random Access 



put nmexp1[,nmexp2\ 

nmexpl specifies a random access file buffer, nmexp=1,2 15. 

nmexp2 specifies the record number in the file, nmexp2i$ the record you 
want to write. If nmexp2 is omitted, the current record number is 
assumed. 



This statement moves data from a file's buffer into a specified place in the file. 
Before PUTting data in a file, you must: 

1 . open the file, thereby assigning a buffer and defining the access mode (must 
be r); 
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2. field the buffer, so you can 

3. place data into the buffer with lset and rset statements. 
When basic encounters the statement: 

put nmexp ,nmexp2 
it does the following: 

8 Gets the information needed to access the disk file 

• Checks the access mode for this buffer (must be r) 

Acquires more disk space for the file if necessary to accommodate the record 
indicated by nmexp2 

• Copies the buffer contents into the specified record of the disk file 
Updates the current record number to equal nmexp2 + 1 

The "current record" is the record whose number is one higher than the last 
record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 

If the record number you put is higher than the end-of-file record number, then 
nmexp2 becomes the new end-of-file record number. 

LSET and RSET 

Place Data in a F } ~ edom Bel r Field 



lset var$ = exp$ and rset var$= expS 
var$ is a field name. 
exp$ contains the data to be placed in the buffer field named by var$. 



These two statements let you place character-string data into fields previously 
set up by a held statement. 

For example, suppose nm$ and ad$ have been defined as field names for a 
random file buffer. nm$ has a length of 18 characters, and ad$ has a length of 
25 characters. 

Now we want to place the following information into the buffer fields so it can 
be written to disk: 
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name: JIM CRICKET, JR. 
address: 2000 EAST PECAN ST, 

This is accomplished with the two statements: 

LSET NM$="JIM CRICKET, JR. " 
LSET AD*="2000 EAST PECAN ST. " 

This puts the data in the buffer as follows: 



JIM CRICKET .JR. 



2000 EAST PECAN ST. 



NM$ 



AB$ 



Note that filler spaces were placed to the right of the data strings in both cases. 
If we had used rset instead of lset statements, the filler spaces would have 
been placed on the left. This is the only difference between lset and rset. 

For example: 

RSET NH$="JIM CRICKET »JR. " 
RSET AD$="2000 EAST PECAN ST. " 

places data in the fields as follows: 



JIM CRICKET, JR, 



2000 EAST PECAN ST. 



NM$ 



AD$ 



If a string item is too large to fit in the specified buffer field, it is always 
truncated on the right. That is, the extra characters on the right are ignored. 

CVD, CVI and CVS 

Restore String to Numeric Form 



£\io(ezp$) 

expS defines an eigiit-cliaraeier string; expS is typically the name of a 
buffer field containing a numeric string. If im(expS)<B, an illegal 

function call error occurs; if iEu(exp$)>B, onty the first eight 
characters are used. 

cw(exp$) 

expS defines a two-character string; exp$is typically the name of a buffer 
field containing a numeric string. If im(tsxp$)<2, an illegal function 
call error occurs; if LEH(exp$)>2, only the first two characters are 
used. 



tmmmsm 
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cvs(exp$) 



exp$ defines a four-character string; exp$ is typically the name of a buffer 
field containing a numeric string. If im(exp$)<4, an illegal function 
call error occurs; if im(exp$)>4, only the first four characters are 

used. 



These functions let you restore data to numeric form after it is read from disk. 
Typically the data has been read by a get statement, and is stored in a random- 
access file buffer. 

The functions cvd, cvi, and cvs are inverses of mkds, mki$, and mks$, 
respectively. 

For example, suppose the name grosspays references an eight-byte field in 
a random-access file buffer, and after GETting a record, grosspays contains a 
mkds representation of the number 13123.38. 

Then the statement: 

PRINT CVD (GROSSPAYS) -TAXES 

prints the result of the difference, 13123.38 -taxes. Whereas the statement: 

PRINT GROSSPAY$-TAXES 

will produce a type mismatch error, since string values cannot be used in 
arithmetic expressions. 

Using the same example, the statement 

A*=CVD( GROSSPAYS) 

assigns the numeric value 13123.38 to the double-precision variable A#. 



End-Of-File Detector 



tQF(nmexp) 

amer.p spaciliss z file buffer, «jfix/j=1,2,...,15. 
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This function checks to see whether all characters up to the end-of-file marker 
have been accessed, so you can avoid input past end errors during sequential 
input. 

Assuming nmexp specifies an open file, then EOF(nmexp) returns (false) when 
the eof record has not yet been read, and - 1 (true) when it has been read. 

Examples 

IF EOF (5) THEN PR I NT "END OF FILE"FILENM$ 
IF EOF(NMX) THEN CLOSE NMZ 

The following sequence of lines reads numeric data from data/txt into the 
array a( ). When the last data character in the file is read, the eof test in line 
30 "passes," so the program branches out of the disk access loop, preventing 
an input past end error from occurring. Also note that the variable I contains 
the number of elements input into array a( ). 

5 DIM A(100) 'ASSUMING THIS IS A SAFE VALUE 

10 OPEN "I" ,1 , "DATA/TXT" 

20 I% = 

30 IF E0F(1) THEN 70 

40 INPUT#1 fA(I%) 

50 IX=IX+1 

60 GOTO 30 

70 REM PROGRAM CONTINUES HERE AFTER DISK INPUT 



LOC 

Get Current Record Number 




imijlie number) 

file number Is a numeric expression specifying the buffer for a currentiy- 
open fife. 



loc is used to determine the current record number, i.e., the number of the last 
record read since the file was opened, loc is only valid after a get. 

Example 

PRINT LOC(l) 
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1310 A$ = "WILLIAM WILSON" 

1320 GET It >!; >( = )<+ 1 

1330 IF N$ = A$ THEN PRINT "FOUND IN RECORD" LOC(i): CLOSE: 

END 
1340 GOTO 1320 

This is a portion of a program. Elsewhere the file has been opened and fielded. 
N$ is a field variable. If N$ matches a$ the record number in which it was found 
is printed. 



C cH EMcMDfMfld Record Number 



lof(nmexp) 

nmexp specifies a random access buffer /Mne*p=1,2,...,15. 



This function tells you the number of the last, i.e. , highest numbered, record 
in a file. It is useful for both sequential and random access. 

For example, during random access to a pre-existing file, you often need a 
way to know when you've read the last valid record, lof provides a way. 

lof is valid as soon as a previously created file is opened. If a file is extended, 
lof is not valid until a get is executed. 



Examples: 



10 OPEN "R" »1 ."UNKNOWN/TXT' 

20 FIELD 1 »255 AS A$ 

30 F0RH,= 1 TO L0F(1) 

40 GET 1 til 

50 PRINT A* 

B0 NEXT 



In line 30, lof(1) specifies the highest record number to be accessed. 

Note: If you attempt to get record numbers beyond the end-of-file record, basic 
simply fills the buffer with hexadecimal zeros, and no error is generated. 



W^^^^^^^^^^M 
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When you want to add to the end of a file, lof tells you where to start adding: 

100 IX=L0F(1)+1 'HIGHEST EXISTING RECORD 
110 PUT 1,11 'ADD NEXT RECORD 



MKB$ ? MKI$, and MKS$ 



MK.a$(nmexp) 

amexp if, ewataafecl as a double-precision numl er. 

mm$(amexp) 

nmexfl is evaluated! « amintepi -32761 nmexp< r M7§B; II mnexp 
excaefis 1P?15> -amp, an illegal functidk cai i error occurs. Any 
fractional component in nmexp r s truncated. 

m$&(nmexp) 

nmexp is evaluated as a single-precision number 



These functions change a number to a "string." Actually the byte values which 
make up the number are not changed; only one byte, the internal data-type 
specifier, is changed, so that numeric data can be placed in a string variable. 

That is: 

mkd$ returns an eight-byte string. 
mki$ returns a two-byte string. 
mks$ returns a four-byte string. 



Examples 

LSET TALLY$=MKI*(IZ) 

Field name tallys would now contain a two-byte representation of the 
integer i%. 

A$=MKI$(8/I) 
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a$ becomes a two-byte representation of the integer portion of 8/1. Any 
fractional portion is ignored. Note that A$ in this case is a normal string 
variable, not a buffer- field name. 

Suppose baseball/bat (a non-standard file extension) has been opened for 
random access using buffer 2, and the buffer has been FiELDed as follows: 

field: NM$ YRS$ AVG$ HR$ AB$ ERNINGS 

length: 16 2 4 2 4 4 

nm$ is intended to hold a character string; avg$, ab$ and ernings, converted 
single-precision values; yrss and hrs, converted integers. 

Suppose we want to write the following data record: 

slow learner played 38 years; lifetime batting average .123; 
career homeruns, 11; at bats, 32768;..., earnings - 13.75. 

Then we'd use the make-string functions as follows: 

1000 LBET NM*="SL0W LEARNER" 

1010 LSET YRS$=MKI$(3B) 

1020 LSET AVG*=MKS*(.123) 

1030 LSET HR*=MKI*( 11 ) 

1040 LSET AB$=MKS$(327G8) 

1050 LSET ERNING*=MKS$<-13,75) 

After this sequence, you can write slow learner's information to disk with 
the put statement. When you read it back from disk with get, you will need 
to restore the numeric data from string to numeric form, using cvi and cvs 
functions. 
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Disk basic provides two means of file access: 

• Sequential — in which you start reading or writing data at the beginning of 
a file; subsequent reads or writes are done at following positions in the file. 

8 Random — in which you start reading or writing at any record you specify. 
(Random access is also called direct access.) 

Sequential access is stream-oriented; that is, the number of characters read or 
written can vary, and is usually determined by delimiters in the data. Random 
access is record-oriented; that is, data is always read or written in fixed-length 
blocks called records. 

To do any input/output to a disk file, you must first open the file. When you 
open the file, you specify what kind of access you want: 

8 o for sequential output 
8 1 for sequential input 

• R for random input/output 

8 e (Extend) for sequential output starting at the end of file. 

You also assign a file buffer for basic to use during file accesses. This number 
can be from 1 to 15, but must not exceed the number of concurrent files you 
requested when you started basic from trsdos. For example, if you started 
basic with 3 files, you can use buffer numbers 1, 2, and 3. Once you assign a 
buffer number to a file, you cannot assign that number to another file until you 
Close the first file. 

Examples 

OPEN "0" > 1 > "TEST" 

Creates a sequential output file named test on the first available drive; if test 
already exists, its previous contents are lost. Buffer 1 will be used for this file. 

OPEN "I" . 2, "TEST" 

Opens test for sequential input, using buffer 2. 

OPEN "R" , It "TEST" 

Opens test for direct access, using buffer 1 . If test does not exist, it will be 
created on the first available drive. Since record length is not specified, 256-byte 
records will be used. 

OPEN "R" » 1 , "TEST" » 40 

Same as preceding example, but 40-byte records will be used. 

OPEN "E" , 1 , "TEST" 

Opens test sequentially for write and positions to eof. 
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This is the simplest way to store data in and retrieve it from a file. It is ideal for 
storing free-form data without wasting space between data items. You read the 
items back in the same order in which they were written. 

There are several important points to keep in mind. 

1 . You must start writing at the beginning of the file. If the data you are seeking 
is somewhere inside, you have to read your way up to it. 

2. Each time you Open a file for sequential output, the file's previous contents 
are lost, unless you use "E" instead of "O" for the mode. 

3. To update (change) a sequential file, read in the file and write out the updated 
data to a new output file. 

4. Data written sequentially usually includes delimiters (markers) to signify 
where each data item begins and ends. To read a file sequentially, you must 
know ahead of time the format of the data. For example: Does the file consist 
of lines of text terminated with carriage returns? Does it consist of numbers 
separated by blank spaces? Does it consist of alternating text and numeric 
information? 

5. Sequential files are always written as ASCII-coded text, one byte for each 
character of data. For example, the number: 

1.2345 
requires 8 bytes of disk storage, including the leading and trailing blanks that 
are supplied. The text string: 

JOHNSON t ROBERT 

requires 15 bytes of disk storage. 

6. Sequential files are always written with a record length of 256. 

Sequential Output: An Example 

Suppose we want to store a table of English-to-metric conversion constants: 



English unit 


Metric equivalent 


1 inch 


2.54001 centimeters 


1 mile 


1 .60935 kilometers 


1 acre 


4046.86 sq. meters 


1 cubic inch 


0.01638716 liter 


1 U.S. gallon 


3.785 liters 


1 liquid quart 


0.9463 liter 


1 lb (avoir) 


0.45359 kilogram 
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First we decide what the data image is going to be. Let's say we want it to look 
like this: 

english unit } metric unit, factor (ENTER) 

For example, the stored data would start out: 



IN->CM» 2,54001 CENTER) 

The following program will create such a data file. 

Note: x'OD' represents a carriage return. 

10 OPEN "0" (1 ,"METRIC/TXT" 

20 FOR IX =1 TO 7 

30 READ UNITS » FACTR 

40 PRINT#1 * UNIT$! " >" 5 FACTR 

50 NEXT 

60 CLOSE 

70 DATA IN->CM> 2,54001, MI->KM» 1.G0935, ACRE->SQ.KMt 

404G.8G E-G 
80 DATA CU,IN->LTR> 1.G38716E-2, GAL->LTR > 3,785 
90 DATA LIQ,QT->LTR» 0,9463, LB->KG» 0,45359 

Line 10 creates a disk file named metric/txt, and assigns buffer 1 for sequential 
output to that file. The extension /txt is used because sequential output always 
stores the data as Ascn-coded text. 

Note: If metric/txt already exists, line 10 will cause all its data to be lost. 
Here's why: Whenever a file is opened for sequential output, the end-of-file 
(eof) is set to the beginning of the file. In effect, trsdos "forgets" that 
anything has ever been written beyond this point. To avoid this, you could use E 
instead of o in line 10. 

Line 40 prints the current contents of units and factr to the file. Since the 
sJJing items do not contain delimiters, it is not necessary to print explicit quotes 
around them. The explicit comma is sufficient. 

Line 60 closes the file. The eof is at the end of the last data item, i.e. , 0.45359, 
so that later, during input, basic will know when it has read all the data. 



The following program reads the data from metric/txt into two "parallel" 
arrays, then asks you to enter a conversion problem. 

5 CLEAR 500 

10 DIM UNIT$(9) t FACTRO) 'allows for up to 10 data pairs 

20 OPEN" I" *1 , "METRIC/TXT" 

25 12=0 

30 IF EOF(l) THEN 70 

40 INPUT*!* UNIT$(I2) »FACTR(I2) 
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50 n,=n,+i 

S0 GOTp 30 

70 CLOSE ' Conversion factors have been read-in 

100 CLS: PRINT TAB(5)"*#* English to Metric Conversions ###" 

110 FOR ITEM?, = TO 17,-1 

120 PRINT TAB (9) .USING" <## ) 1 1 "5 ITEM'/, > 

UNIT* (ITEM?,) 
130 NEXT 

140 PRINT @ 704 i "Which conversion (0-B)"i 
150 INPUT CHOICE! 

1B0 INPUT"Enter English quantity" .U 

170 PRINT"The Metric equivalent is" Y*FACTR(CHOICEZ) 
180 INPUT"Press <ENTER> to continue" iX 
190 PRINT i 704 > CHR$(31) 'clear to end of frame 
200 GOTO 140 

Line 20 opens the file for sequential input. Input begins at the beginning of 
the file. 

Line 30 checks to see that the end-of-file record hasn't been reached. If it has, 
control branches from the disk input loop to the part of the program that uses 
the newly acquired data. 

Line 40 reads a value into the string array unit$( ), and a number into the 
single-precision array factr( ). Note that this input list parallels the print# list 
that created the data file (see the section "Sequential Output: An Example"). 
This parallelism is not required, however. We could just as successfully have 
used: 

40 INPUT*! , UNIT$(IX): INPUT*1 »FACTR< 11 ) 



How to update a ile 



Suppose you want to add more entries into the English-Metric conversion file. 
You could simply re-Open the file with mode = e and print# the extra data. 
Or, you might want to leave the old file intact and output a new file: 

1 . Open the file for sequential input (Mode = i) 

2. Open another new data file for sequential output (Mode = o) 

3 . Input a block of data and update the data as necessary 

4. Output the data to the new file 

5. Repeat steps 3 and 4 until all data has been read, updated, and output to the 
new file; then go to step 6 

6. Close both files 
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Using the line-oriented input, you can write programs that edit other basic 
program files: renumber them, change lprints to prints, etc. — as long as these 
"target" programs are stored in ascii format. 

The following program counts the number of lines in any ascii — format basic 
disk file with the extension /txt. 

10 CLEAR 300 

20 INPUF'WHAT IB THE NAME OF THE PROGRAM"! PROG* 

30 IF INSTR(PROG*»"/TXT">=0 THEN 110 'require /TXT extension 

40 OPEN" I " i 1 i PROG* 

50 n, = 

G0 IF E0F(1) THEN 90 

70 I%=IX+1: LINE INPUT#1 > TEMP* 

80 GOTO G0 

90 PRINT PROG*" IB" 11 "LINES LONG," 

100 CLOSE: GOTO 20 

110 PRINT "FILEBPEC MUST INCLUDE THE EXTENSION '/TXT'" 

120 GOTO 20 

For basic programs stored in ascii, each program line ends with a carriage 
return character not preceded by a line feed. So the line input in line 70 
automatically reads one entire line at a time, into the variable temps. Variable 
i% actually does the counting. 

To try out the program, first save any basic program using the A (ascii) option 
(See save). Use the extension /txt. 
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Random access offers several advantages over sequential access: 

• Instead of having to start reading at the beginning of a file, you can read any 
record you specify. 

• To update a file, you don't have to read in the entire file, update the data, and 
write it out again. You can rewrite or add to any record you choose, without 
having to go through any of the other records. 

• Random access is more efficient — data takes up less space and is read and 
written faster. 

" Opening a file for direct access allows you to write and read from the file via 
the same buffer. 

- Random access provides many powerful statements and functions to structure 
your data. Once you have set up the structure, direct input/output becomes 
quite simple. 

The last advantage listed above is also the "hard part" of direct access. It takes 
a little extra thought. 

For the purposes of direct access, you can think of a disk file as a set of boxes 

— like a wall of post-office boxes. Just like the post office receptacles, the file 
boxes are numbered. We call these boxes "records." 

You can place data in any record, or read the contents of any record, with 
statements like: 

PUT 1 >5 write buffer- 1 contents to record 5 

GET 1 f5 read the contents of record 5 into buffer- 1 

In Figure 14, we assume a record length of 256. 




('256 1 

Kbytes/ 

#6 



/ 236 
VBYTES 

#1 



(ZS6 ) 
\BYTES/ 

#7 



/ 256 \ 

Uytes,/ 

#2 



/256 \ 

Ibytes/ 



#8 



f 256 \ 
Kbytes/ 

#3 



Kbytes/ 

#9 



/256 \ 
V BYTES/ 

#4 



f 256 ' 
i BYTES; 



#10 



258 

StTE8 

#5 




RECORDS IN DISK FILE 
Figure 14. get and put. 



I/O BUFFERS IN RAM 
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The buffer is a waiting area for the data. Before writing data to a file, you must 
place it in the buffer assigned to the file. After reading data from a file, you 
must retrieve it from the buffer. 

As you can see from the sample put and get statements above, data is passed to 
and from the disk in records. The size of each record is determined by an Open 
statement. 



storing Data in a Butter 

You must place the entire record into the buffer before putting its contents into 
the disk file. 

This is accomplished by 1) dividing the buffer up into fields and naming them, 
then 2) placing the string or numeric data into the fields. 

For example, suppose we want to store a glossary on disk. Each record will 
consist of a word followed by its definition. We start with: 

100 0PEN"R"» 1* "GLOSBARY/BAS" 

110 FIELD 1, 1G AS WD$» 240 AS MEANING* 

Line 100 opens a file named glossary/bas (creates it if it doesn't already exist); 
and gives buffer 1 direct access to the file. 

Line 1 10 defines two fields onto buffer 1: 

wd$ consists of the first 16 bytes of the buffer; 

meanings consists of the last 240 bytes. 

wd$ and meanings are now field-names 

What makes field names different? Most string variables point to an area in 
memory called the string space. This is where the value of the string is stored. 

Field names, on the other hand, point to the buffer area assigned in the field 
statement. So, for example, the statement: 

10 PRINT WD$i ":"S MEANINGS 

displays the contents of the two buffer fields defined above. 

These values are meaningless unless we first place data in the buffer, lset, rset 
and get can all be used to accomplish this function. We'll start with lset and 
rset, which are used in preparation for disk output. 

Our first entry is the word "left-justify" followed by its definition. 

100 0PEN"R"» It "GLOSSARY/BAS" 

110 FIELD It 1G AS WD$, 240 AS MEANING* 

120 LSET WD$="LEFT-JUSTIFY" 

130 LSET MEANING$="T0 PLACE A VALUE IN A FIELD FROM LEFT TO 
RIGHT? IF THE DATA DOESN'T FILL THE FIELD* BLANKS ARE 
ADDED ON THE RIGHT! IF THE DATA IS TOO LONG. THE EXTRA 
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CHARACTERS ON THE RIGHT ARE IGNORED. LSET IB A LEFT- 
JUSTIFY FUNCTION," 

Line 120 left-justifies the value in quotes into the first field in buffer 1 . Line 130 
does the same thing to its quoted string. 

Notes rset would place filler-blanks to the left of the item. Truncation would 
still be on the right. 

Now that the data is in the buffer, we can write it to disk with a simple put 
statement: 

140 PUT 1 .1 
150 CLOSE 

This writes the first record into the file gloss ary/b as. 

To read and print the first record in glossary/bas, use the following sequence: 

1G0 0PEN"R" > It "GLOSSARY/BAS" 

170 FIELD It IB AS WD$ > 240 AS HEANING* 

180 GET 1 (1 

190 PRINT WD$: PRINT MEANING$ 

200 CLOSE 

Line 160 and 170 are required only because we closed the file in line 150. If we 
hadn't closed it, we could go directly to line 180. 
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om Access: A General 
rtore 



The previous example shows the necessary sequences to read and write using 
random access. But it does not demonstrate the primary advantages of this form 
of access — in particular, it doesn't show how to update existing files by going 
directly to the desired record. 

The program below, gloss acc/bas, develops the glossary example to show 
some of the techniques of random access for file maintenance. But before 
looking at the program, study this general procedure for creating and 
maintaining files via random access. 



Step 


See GLOSSACC/BAS, 
Line Number 


1. Open the file 

2. Field the buffer 

3. Get the record to be updated 

4. Display current contents of the record (use 
CVD, CVI, CVS before displaying numeric 
data) 

5. LSET and RSET new values into the fields 
(use MKD$, MKI$, MKS$ with numeric data 
before setting it into the buffer) 

6. PUT the updated record 

7. To update another record, continue at step 3. 
Otherwise, go to step 8. 

8. Close the file 


110 

120 

140 

145-170 

210-230 

240 
250-260 

270 



REM GLOSSACC/BAS ,, , 

00 CLS : CLEAR 300 

10 OPEN "R"» if "GL0SSARY/BAS" 

20 FIELD It IS AS WD* > 238 AS MEANING* > 2 AS NX* 

30 INPUT "WHAT RECORD DO YOU WANT TO ACCESS"! RZ 

40 GET 1 > HI 

45 NX% = CUHNX*) 'SAME LINK TO NEXT ALPHABETICAL ENTR 

50 PRINT "WORD : "WD* 

(30 PRINT "DEF'N : " : PRINT MEANING* 

70 PRINT "NEXT ALPHABETICAL ENTRY: RECORD »:" NXZ 



80 W* = ' 

W$ 
190 D* = ' 

OK?" : 
200 INPUT 
210 IF W* 
220 IF D* 



INPUT "TYPE NEW WORD < ENTER) OR 



PRINT 
ENTER) IF OK' 



' : PRINT "TYPE NEW DEF'N < ENTER) OR < ENTER) IF 
LINE INPUT D$ 

'TYPE NEW SEQUENCE NUMBER OR -(ENTER) IF OK " i NXZ 
:> "" THEN LSET WD* = W$ 
:> "" THEN LSET MEANING* = D* 
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230 LSET NX* = MKI* (NXX) 

240 PUT 1 * R7„ 

2/15 Rl = m<l 'USE NEXT ALPHA, LINK AS DEFAULT FOR t 

250 CLS : PRINT " TYPE <ENTER> TO READ NEXT ALPHA, 

PRINT" OR RECORD # <ENTER> FOR SPECIFIC ENTRY* 1 

OR < ENTER) TO QUIT"; Rl 

IF ®<Rl THEN 140 

CLOSE 



IEXT RECORD 
ENTRY,": 
: INPUT " 



2B0 
270 
280 END 



Notice we've added a field, nx$, to the record (line 120). nx$ will contain the 
number of the record which comes next in alphabetical sequence. This enables 
us to proceed alphabetically through the glossary, provided we know which 
record contains the entry which should come first. 

For example, suppose the glossary contains: 



reeord# 


word (WD$) 


defn, 


pointer to next 

alpha, entry (NX$) 


1 
2 
3 

4 


LEFT-JUSTIFY 
BYTE 

RIGHT-JUSTIFY 
HEXADECIMAL 




3 
4 

1 



When we read record 2 (byte), it tells us that record 4 (hexadecimal) is next, 
which then tells us record 1 (left-justify) is next, etc. The last entry, record 3 
(right-justify), points us to zero, which we take to mean "The End." 

Since nx$ will contain an integer, we have to first convert that number to a two- 
byte string representation, using mki$ (line 230 above). 

The following program displays the glossary in alphabetical sequence: 

300 REM , , , GLOSSOUT/BAS , ,, 

310 CLS : CLEAR 300 

320 OPEN "R" , 1, "GLOSSARY/BAS" 

330 FIELD 1, IB AS WD* , 238 AS MEANING*, 2 AS NX* 

340 INPUT "WHICH RECORD IS FIRST ALPHABETICALLY"; HI 

350 GET 1 , HI 

3G0 PRINT : PRINT WD* 

370 PRINT MEANING* 

3B0 HI = CM I (NX*) 

390 INPUT "PRESS <ENTER> TO CONTINUE"? X 

400 IF HI <> THEN 350 

410 CLOSE 

420 END 
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Disk BASIC Error Codes/Messages 




51 


Field overflow 


52 


Internal error 


53 


Bad file number 


54 


File not found 


55 


Bad file mode 


58 


Disk i/o error 


62 


Disk full 


63 


Input past end 


64 


Bad record number 


65 


Bad file name 


67 


Direct statement in file 


68 


Too many files 


69 


Disk write-protect 


70 


File access 



Note: Disk errors cannot be simulated via the error statement. 
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Subject Page 

Abbreviate 14 

APPEND 26 

ASCII 26, 53 

ATTRIB 10, 24, 27, 60 

AUTO 29, 72 

BACKUP 8, 25, 57, 67 

BASIC 17 

BASIC* 91 

Baud 12,62 

Bits i, 62 

BKSPC 82 

(BREAK) 29, 31 , 44, 96 

Buffer 91, 123 

BUILD 29,31,45,57 

Byte i, 18, 62, 74 

Cable (Ribbon) 1,2 

Cass? 12 

CLEAR 31 , 32, 45, 72 

CLOCK 33 

CLOSE 125 

CLOAD 63 

CLS 33 

CMD"A" 93, 95 

CMD"B" 93, 96 

CMD"C" 93, 96 

CMD"D" 93, 97 

CMD"E" 93, 98 

CMD'T' 93, 98 

CMD"J" 93, 99 

CMD"L" 93, 100 

CMD"0" 93, 101 

CMD"P" 93, 102 

CMD"R" 93, 103 

CMD"S" 93, 103 

CMD'T" 93, 104 

CMD"X" 93, 104 

CMD"Z" 93, 105 

Commands 

Auto 29-30 

Entering 20 

Forms of 21 



Subject Page 

Library 26-66 

Syntax 20 

Utility 67-89 

CONVERT 8, 10, 25, 68 

COPY 34, 50 

CREATE 35 

CSAVE 63 

CVD, CVI, CVS 139-40 

Data Diskette See Diskette 

DATE 36, 37 

DCB 76 

DEBUG 37 

DEFFN 93,106 

Definitions 

Comments 21-2 

Delimiter 22 

Filename 21-2 

Options 22 

DEF USR 93, 108 

DIR 25,27,44 

Disk BASIC 

Abbreviations 95 

Instructions 11,12 

Starting 11, 91-2 

Disk Drive 

Oand 1 1,4, 6, 10, 34, 55 

2, 3 (External) 1,4 

Expansion 1,4 

Installation 1,4 

Diskette 

Care 5 

Data i, 24 

Description 5 

Inserting 5, 7 

Labelling 6 

Notch-protect 5 

Organization 74 

Specifications 15 

System i, 6, 24 

DIVIDE 83 

DMULT 84 

DO 31,32,46,57,71 

Drive Specification 23 

DUAL 47 

DUMP 48,54,59 
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Subject 

EOF (End-of-file) 45, 75, 1 40-1 

ERROR 49 

Error 13 

DiskBASIC 155 

TRSDOS 90 

Extents See Technical Information 

FIELD 134-6 

File 

Access 116, 123, 145 

APPEND 26 

COPY 34 

Manipulation 116,118 

System vs User 25 

Variable Length 91 

Filename 23, 44 

File Specification 22 

FILPTR 85 

FORMAT 8,9,25,70 

FORMS 49 

FREE 35, 50 

GET 136-7 

Granules 

Allocation 50 

Defined 74 

Number of 45, 51 , 74 

HELP 51,53 

HERZ50 71 

Hexadecimal 32, 38, 41 , 48, 53 

55, 59, 93, 94 

INIT 78 

INPUT # 126-30 

Installation 1-3 

INSTR 93,108 

I/O 32, 61 

I/O Calls 75, 77-89 

KILL 52,118 

LSET 138-9 

LIB 53 

LINE INPUT 110,93 

LINE INPUT # 130-1 

LIST 53 

LOAD 12, 54, 118 

Load 11 

LOC 141-2 

LOF 142 

LPC 71 

Maintenance 13 

MASTER 55, 64 

Memory 

Display 38 

Map 19 

User 38, 59 



Page 

Memory Size? 11 

MEMTEST 72 

MERGE 119 

MID$ 93, 111 

MKD$, MKI$, MKS$ 143-4 

NAME 93,112 

NEW 11 

Notations/Abbreviations 14 

Octal 93, 94 

OPEN 123,4 

Operation 4 

Password 8, 24, 25, 27 

57, 60, 67, 69 

Access 27 

Changing 27 

Master 9, 25 

Protecting 69 

Update 27 

PATCH 12,55 

PAUSE 56 

POSEOF 82 

POSN 79 

Power On/Off 4, 30 

PRINT # 131-3 

Printer 31,47, 105 

Programming ii, 1 1 

PROT 10,25,57 

PURGE 25, 58 

PUT 137-8 

PUTEXT 81 

RAM 18, 32, 40, 64, 71 , 73 

RAMDIR 84 

Random File Access 150-4 

General Procedure 153 

Techniques 1 50 

READ 70 

Record Length 35, 45 

Logical Length 26, 35, 45, 76 

Number of 45, 77 

Physical 77 

RELO 59 

RENAME 35, 60 

Reset 30, 73 

Location 4 

REWIND 82 

ROM 73 

ROUTE 47, 61 

RSET 138-9 

RS-232-C 62 

RUN 120 

SAVE 11,121 
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Save 11 

Sector 77 

SETCOM 62 

Sequential File Access 146-149 

Sequential Input 1 47 

Sequential Line Input 149 

Sequential Output 146 

Starting 

Auto 29 

DiskBASIC 11 

System 6 

TRSDOS 7 

Specifications 15 

System Diskette See "Diskette" 

Syntax 83 

TAPE 63 

TIME 64 

Troubleshooting 7, 1 3 

TRSDOS 

Definition 17-19 

Start-up 7 

Using 20 

USING 133-4 

USRn 93,113 

VERF 81 

Videooutput 47, 105 

WP 65 

WRITE 80-1 

Write-protect notch 5 

XFERSYS 73 

Z-80 37, 39, 40, 41 , 48 

55, 56, 63 
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Figures and Tables 

A Diskette 5 
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Directory Listing (dir) 45 
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Free Map (free) 51 

Full-Screen Format (debug) 43 
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Half-Screen Format (debug) 40 
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Radio Shack Software License 

The following are the terms and conditions of the Radio Shack Software License for 
copies of Radio Shack software either purchased by the customer, or received with 
or as part of hardware purchased by customer: 

A. Radio Shack grants to CUSTOMER a personal, non-exclusive, paid up license to 
use the Radio Shack computer software programs received. Title to the media 
on which the software is recorded (cassette and/or disk) or stored ( ROM ) is 
transferred to the CUSTOMER, but not title to the software. 

B. In consideration for this license. CUSTOMER shall not reproduce copies of such 
software programs except to produce the number of copies required for 
personal use by CUSTOMER (if the software allows a backup copy to be made), 
and to include Radio Shack's copyright notice on all copies of programs 
reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications software 
(modified or not, in whole or in part), provided CUSTOMER has purchased one 
copy of the software for each one resold. The provisions of this Software 
License (paragraphs A, B, and C) shall also be applicable to third parties 
purchasing such software from CUSTOMER . 

Important Note 

All Radio Shack computer programs are licensed on an "as is" basis without 
warranty. 

Radio Shack shall have no liability or responsibility to customer or any other person 
or entity with respect to any liability, loss or damage caused or alleged to be caused 
directly or indirectly by computer equipment or programs sold by Radio Shack, 
including but not limited to any interruption of service, loss of business or 
anticipatory profits or consequential damages resulting from the use or operation of 
such computer or computer programs. 

Good data processing procedure dictates that the user test the program, run and test 
sample sets of data, and run the system in parallel with the system previously in use 
for a period of time adequate to insure that results of operation of the computer or 
program are satisfactory. 
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service Policy 

Radio Shack's nationwide network of service facilities provides quick, convenient, 
and reliable repair services for all of its computer products , in most instances . 
Warranty service will be performed in accordance with Radio Shack's Limited 
Warranty. Non-warranty service will be provided at reasonable parts and labor 
costs. 

Because of the sensitivity of computer equipment, and the problems which can 
result from improper servicing, the following limitations also apply to the services 
offered by Radio Shack: 

1 . If any of the warranty seals on any Radio Shack computer products are broken, 
Radio Shack reserves the right to refuse to service the equipment or to void any 
remaining warranty on the equipment. 

2. If any Radio Shack computer equipment has been modified so that it is not 
within manufacturer's specifications, including, but not limited to, the 
installation of any non-Radio Shack parts, components, or replacement boards, 
then Radio Shack reserves the right to refuse to service the equipment, void any 
remaining warranty, remove and replace any non-Radio Shack part found in the 
equipment, and perform whatever modifications are necessary to return the 
equipment to original factory manufacturer's specifications. 

3 . The cost for the labor and parts required to return the Radio Shack computer 
equipment to original manufacturer's specifications will be charged to the 
customer in addition to the normal repair charge. 
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Radio Shack shall have no liability or responsibility to customer or any 
other person or entity with respect to any liability, loss or damage caused 
or alleged to be caused directly or indirectly by computer equipment or 
programs sold by Radio Shack, including but not limited to any interrup- 
tion of service, loss of business or anticipatory profits or consequential 
damages resulting from the use or operation of such computer or 
computer programs. 

NOTE: Good data processing procedure dictates that the user test the 
program, run and test sample sets of data, and run the system in 
parallel with the system previously in use for a period of time 
adequate to insure that results of operation of the computer or 
program are satisfactory. 

RADIO SHACK SOFTWARE LICENSE 

A. Radio Shack grants to CUSTOMER a non-exclusive, paid up license to 
use on CUSTOMER'S computer the Radio Shack computer software 
received. Title to the media on which the software is recorded (cassette 
and/or disk) or stored (ROM) is transferred to the CUSTOMER, but not 
title to the software. 

B. In consideration for this license, CUSTOMER shall not reproduce 
copies of Radio Shack software except to reproduce the number of copies 
required for use on CUSTOMER'S computer (if the software allows a 
backup copy to be made), and shall include Radio Shack's copyright 
notice on all copies of software reproduced in whole or in part. 
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C. CUSTOMER may resell Radio Shack's system and applications soft- 
ware (modified or not, in whole or in part), provided CUSTOMER has 
purchased one copy of the software for each one resold. The provisions 
of this software License (paragraphs A, B, and C) shall also be applicable 
to third parties purchasing such software from CUSTOMER. 
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LIMITED WARRANTY 

For a period of 90 days from the date of delivery, Radio Shack warrants to the 
original purchaser that the computer hardware unit shall be free from manufac- 
turing defects. This warranty is only applicable to the original purchaser who 
purchased the unit from Radio Shack company-owned retail outlets or duly 
authorized Radio Shack franchisees and dealers. This warranty is voided if the 
unit is sold ortransferred by purchaser to a third party. This warranty shall be 
void if this unit's case or cabinet is opened, if the unit has been subjected to 
improper or abnormal use, or if the unit is altered or modified, if a defect occurs 
during the warranty period, the unit must be returned to a Radio Shack store, 
franchisee, or dealer for repair, along with the sales ticket or lease agreement. 
Purchaser's sole and exclusive remedy in the event of defect is limited to the 
correction of the defect by adjustment, repair, replacement, or complete 
refund at Radio Shack's election and sole expense. Radio Shack shall have no 
obligation to replace or repair expendable items. 

Any statements made by Radio Shack and its employees, including but not 
limited to, statements regarding capacity, suitability for use, or performance of 
the unit shall not be deemed a warranty or representation by Radio Shack for 
any purpose, nor give rise to any liability or obligation of Radio Shack. 

EXCEPT AS SPECIFICALLY PROVIDED IN THIS WARRANTY OR IN THE 
RADIO SHACK COMPUTER SALES AGREEMENT, THERE ARE NO 
OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL RADIO 
SHACK BE LIABLE FOR LOSS OF PROFITS OR BENEFITS, INDIRECT, 
SPECIAL, CONSEQUENTIAL OR OTHER SIMILAR DAMAGES ARISING 
OUT OF ANY BREACH OF THIS WARRANTY OR OTHERWISE. 
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